home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / basic / dialogic.zip / DIALOGIC.DOC < prev    next >
Text File  |  1990-01-31  |  212KB  |  6,588 lines
  1. January 30, 1990
  2.  
  3.  
  4. ====================================
  5. Important note to BBS-version users:
  6. ====================================
  7.  
  8. This is the actual DiaLogic product documentation.  It has been presented
  9. in its entirety and is supplemented by the accompanying README file, which
  10. should be read before this document.  Please realize that references to
  11. DIALOGIC.BAS and DIALOGIC.LIB are intended for the registered copy of
  12. DiaLogic.  These files are not present in the BBS version.
  13.  
  14. Further, some aspects of the document are formatted very differently from
  15. the printed version simply because this manuscript has been converted from
  16. a desktop publishing version to an ASCII format.  We wanted to provide you
  17. with complete documentation to DiaLogic, and we sincerely apologize for any
  18. loss in readability.
  19.  
  20.  
  21.                                  *
  22.                           Dialog Software
  23.                  Box 9889 at 1101 Wilson Boulevard
  24.                   Arlington, Virginia 22209-0889
  25.                           (703) 528-1505
  26.  
  27.  
  28.  
  29.   LICENSE AGREEMENT
  30.  
  31.   Dialog Software grants a license to use the enclosed software and printed
  32.   documentation to the original purchaser.   Copies may be made for back-up
  33.   purposes  only.    Copies  made  for  any  other  purpose  are  expressly
  34.   prohibited,  and adherence to this requirement is the sole responsibility
  35.   of the purchaser.   However, the purchaser does retain the  right to sell
  36.   or distribute programs  that contain  DiaLogic routines, so  long as  the
  37.   primary purpose of the included routines is to augment the software being
  38.   sold  or  distributed.   Source code  for any  component of  the DiaLogic
  39.   program may not be distributed under any circumstances.  This license may
  40.   be  transferred to  a third  party  only if  all existing  copies  of the
  41.   software and documentation are also transferred.
  42.  
  43.   WARRANTY INFORMATION
  44.  
  45.   Dialog Software  warrants that this  product will perform  as advertised.
  46.   In the event that  it does not meet the terms of  this warranty, and only
  47.   in that  event, Dialog  Software will replace  the product or  refund the
  48.   amount paid, if notified within 30  days of purchase.  Proof of  purchase
  49.   must be returned with the product, as well as a brief description  of how
  50.   it fails to meet the advertised claims.
  51.  
  52.   DIALOG SOFTWARE'S LIABILITY IS LIMITED  TO THE PURCHASE PRICE.   Under no
  53.   circumstances shall Dialog  Software or  the authors of  this product  be
  54.   liable for any incidental  or consequential damages, nor for  any damages
  55.   in excess of the original purchase price.
  56.  
  57.  
  58.  
  59.  
  60.   DiaLogic.
  61.  
  62.   Entire contents Copyright   1989 by Jonathan S. Waldman, Ethan Winer,
  63.   Crescent Software, and Dialog Software.  All rights reserved.
  64.  
  65.   No  portion of this  software or manual  may be duplicated  in any manner
  66.   without the written permission of Jonathan S. Waldman or Dialog Software.
  67.  
  68.   QuickBASIC is a trademark of Microsoft Corp.
  69.  
  70.   Dialog Software
  71.   Box 9889
  72.   1101 Wilson Boulevard
  73.   Arlington, Virginia 22209
  74.   (703) 528-1505
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.                                    DiaLogic
  88.                         Written By Jonathan S. Waldman
  89.  
  90.                       Dedicated to my mother and father,
  91.                for having started my adventure into computers.
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.                A special thanks, with love, to Donna LeMaitre.
  103.  
  104.              Also, to Microsoft, Stephanie, Nancy, Ethan Winer:
  105.    
  106.  
  107.                            Thanks for your support!
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.   DiaLogic
  117.  
  118.   INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . . . . . . .     i
  119.      Welcome  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   iii
  120.           Thanks! . . . . . . . . . . . . . . . . . . . . . . . . . .   iii
  121.           Registration & Upgrades . . . . . . . . . . . . . . . . . .   iii
  122.      DiaLogic at a Glance . . . . . . . . . . . . . . . . . . . . . . .  iv
  123.           A Standard  . . . . . . . . . . . . . . . . . . . . . . . . .  iv
  124.           Sophisticated, Elegant, & Powerful  . . . . . . . . . . . . .  iv
  125.           Practical . . . . . . . . . . . . . . . . . . . . . . . . . .   v
  126.      Compatibility  . . . . . . . . . . . . . . . . . . . . . . . . . .  vi
  127.           System  . . . . . . . . . . . . . . . . . . . . . . . . . . .  vi
  128.           QuickBASIC  . . . . . . . . . . . . . . . . . . . . . . . . .  vi
  129.      Using This Manual  . . . . . . . . . . . . . . . . . . . . . . . .  vi
  130.           Intended Audience . . . . . . . . . . . . . . . . . . . . . .  vi
  131.           Contents  . . . . . . . . . . . . . . . . . . . . . . . . . .  vi
  132.           Notational Conventions  . . . . . . . . . . . . . . . . . .  viii
  133.      Technical Support  . . . . . . . . . . . . . . . . . . . . . . .    xi
  134.   PART I: GETTING STARTED . . . . . . . . . . . . . . . . . . . . . . .   1
  135.      Quick Start  . . . . . . . . . . . . . . . . . . . . . . . . . . .   3
  136.      Things To Do First . . . . . . . . . . . . . . . . . . . . . . . .   3
  137.           The Demo  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
  138.           README  . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
  139.      Installation . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
  140.           What's On The Diskette  . . . . . . . . . . . . . . . . . . .   4
  141.           Copying and Backing Up  . . . . . . . . . . . . . . . . . . .   5
  142.           Loading the Source Code . . . . . . . . . . . . . . . . . . .   5
  143.   PART II: DIALOG BOX BASICS  . . . . . . . . . . . . . . . . . . . . .   7
  144.      Overview of DiaLogic's Operation . . . . . . . . . . . . . . . . .   9
  145.           Arguments in the Call . . . . . . . . . . . . . . . . . . . .   9
  146.           The Use of Ambiguous Variable Names . . . . . . . . . . . . .  10
  147.      Terms & Concepts . . . . . . . . . . . . . . . . . . . . . . . . .  13
  148.           The Elements  . . . . . . . . . . . . . . . . . . . . . . . .  13
  149.           The Input Focus . . . . . . . . . . . . . . . . . . . . . . .  14
  150.           Alt-keys  . . . . . . . . . . . . . . . . . . . . . . . . . .  15
  151.           The Tilde (~) Character . . . . . . . . . . . . . . . . . . .  15
  152.           The DB() Array  . . . . . . . . . . . . . . . . . . . . . . .  17
  153.           The LB() Array  . . . . . . . . . . . . . . . . . . . . . . .  19
  154.           The Dialog Box Template . . . . . . . . . . . . . . . . . . .  21
  155.           Include Files . . . . . . . . . . . . . . . . . . . . . . . .  22
  156.  
  157.  
  158.  
  159.  
  160.                                                           Table of Contents
  161.  
  162.      DB() Variable Values . . . . . . . . . . . . . . . . . . . . . . .  24
  163.           Color . . . . . . . . . . . . . . . . . . . . . . . . . . . .  24
  164.           Borders . . . . . . . . . . . . . . . . . . . . . . . . . . .  26
  165.           Default Values  . . . . . . . . . . . . . . . . . . . . . . .  27
  166.      Understanding the Elements . . . . . . . . . . . . . . . . . . . .  27
  167.           The Window  . . . . . . . . . . . . . . . . . . . . . . . . .  28
  168.           Text Box  . . . . . . . . . . . . . . . . . . . . . . . . . .  31
  169.           List Box  . . . . . . . . . . . . . . . . . . . . . . . . . .  34
  170.           Check Box . . . . . . . . . . . . . . . . . . . . . . . . . .  42
  171.           Option Buttons  . . . . . . . . . . . . . . . . . . . . . . .  44
  172.           Smart Labels  . . . . . . . . . . . . . . . . . . . . . . . .  47
  173.           Command Buttons . . . . . . . . . . . . . . . . . . . . . . .  50
  174.           Group Box . . . . . . . . . . . . . . . . . . . . . . . . . .  53
  175.   PART III: CREATING A TEMPLATE . . . . . . . . . . . . . . . . . . . .  55
  176.      Summary  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  57
  177.      A Detailed Example . . . . . . . . . . . . . . . . . . . . . . . .  57
  178.           Making a Sketch . . . . . . . . . . . . . . . . . . . . . . .  58
  179.           Determining the Sequence  . . . . . . . . . . . . . . . . . .  59
  180.           Copying & Pasting . . . . . . . . . . . . . . . . . . . . . .  60
  181.           Making the Assignments  . . . . . . . . . . . . . . . . . . .  63
  182.   PART IV: GENERATING A DIALOG BOX  . . . . . . . . . . . . . . . . . .  71
  183.      Preparing for the Call . . . . . . . . . . . . . . . . . . . . . .  73
  184.           Including DIALOGIC.BI . . . . . . . . . . . . . . . . . . . .  74
  185.           Initializing the Mouse  . . . . . . . . . . . . . . . . . . .  74
  186.           REDIMing DiaLogic's Arrays  . . . . . . . . . . . . . . . . .  77
  187.           Setting the Level . . . . . . . . . . . . . . . . . . . . . .  78
  188.           Including the Dialog Box Template . . . . . . . . . . . . . .  80
  189.           Setting the Action  . . . . . . . . . . . . . . . . . . . . .  81
  190.           Setting the Focus . . . . . . . . . . . . . . . . . . . . . .  83
  191.           Ky$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  83
  192.      Making the Call  . . . . . . . . . . . . . . . . . . . . . . . . .  84
  193.      Processing the Call  . . . . . . . . . . . . . . . . . . . . . . .  85
  194.   PART V: CREATING STANDALONE PROGRAMS  . . . . . . . . . . . . . . . .  92
  195.      Compiling DiaLogic . . . . . . . . . . . . . . . . . . . . . . . .  94
  196.      Linking with DiaLogic  . . . . . . . . . . . . . . . . . . . . . .  94
  197.      Adding to the DIALOGIC Quick Library . . . . . . . . . . . . . . .  96
  198.  
  199.  
  200.  
  201.  
  202.   DiaLogic
  203.  
  204.   PART VI: ADVANCED TOPICS  . . . . . . . . . . . . . . . . . . . . .    99
  205.      Choosing a Dialog Box Type . . . . . . . . . . . . . . . . . . .   102
  206.      Single-Tasking Dialog Boxes  . . . . . . . . . . . . . . . . . .   103
  207.      Multi-Tasking Dialog Boxes . . . . . . . . . . . . . . . . . . .   107
  208.      Stacked Dialog Boxes . . . . . . . . . . . . . . . . . . . . . .   109
  209.           Overview  . . . . . . . . . . . . . . . . . . . . . . . . .   109
  210.           Single-Tasking Stacked Dialog Boxes . . . . . . . . . . . .   111
  211.           Multi-Tasking Stacked Dialog Boxes  . . . . . . . . . . . .   112
  212.   APPENDICES  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   115
  213.      DIALOG BOX ELEMENTS  . . . . . . . . . . . . . . . . . . . . . .   A-1
  214.      MODIFYING DIALOGIC.BAS . . . . . . . . . . . . . . . . . . . . .   B-1
  215.      TROUBLESHOOTING  . . . . . . . . . . . . . . . . . . . . . . . .   C-1
  216.      Dialog SOFTWARE COLOR CHART  . . . . . . . . . . . . . . . . . .   D-1
  217.      ASCII CHARACTER CHARTS . . . . . . . . . . . . . . . . . . . . .   E-1
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.                                    DiaLogic
  235.                                  Version 1.4E
  236.                                January 31, 1990
  237.  
  238.                                      THE
  239.                                  INTRODUCTION
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.                                                                Introduction
  247.  
  248.   Welcome
  249.  
  250.   We have put  every effort into making  this the finest and  most powerful
  251.   dialog box program available.   We sincerely hope that  you love it.   If
  252.   you  have a  comment, a  complaint, or  perhaps a suggestion  for another
  253.   product you would  like to see, please let  us know.  We want  to be your
  254.   favorite software company.
  255.  
  256.   Registration & Upgrades
  257.  
  258.   Please take a  few moments  to fill out  the enclosed registration  card.
  259.   Doing this entitles  you to free technical  support by phone, as  well as
  260.   insuring that  you are  notified of possible  upgrades and  new products.
  261.   Many upgrades  are offered at little or  no cost, but we  cannot tell you
  262.   about them unless we know who you are!
  263.  
  264.   Also, please mark the product serial number on your disk labels.  License
  265.   agreements  and registration  forms  have an  irritating way  of becoming
  266.   lost.  Writing the serial number on the diskette will keep it handy.
  267.  
  268.   You may also  want to note the  version number in a  convenient location,
  269.   since it is stored directly on the distribution disk in the volume label.
  270.   If you ever  have occasion to  call us for  assistance, we will  probably
  271.   need to know the version number you are using.   To determine the version
  272.   number please look at the first page of the DiaLogic.BAS source code.
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.                                               iii
  291.  
  292.  
  293.  
  294.  
  295.   DiaLogic
  296.  
  297.   We are constantly improving all of our products, so you may  want to call
  298.   periodically to ask for the  current version number.  Major upgrades  are
  299.   always announced, however minor fixes or additions generally are not.  If
  300.   you are  having any problems at all, even if  you are sure it is not with
  301.   one of our products, please call or write to us. 
  302.  
  303.  
  304.   DiaLogic at a Glance
  305.  
  306.   A Standard
  307.  
  308.   DiaLogic gives  the professional and  hobbyist programmer the  ability to
  309.  
  310.   develop  programs which  have the  same standardized interface  which has
  311.   become a  sensation in  the computer industry.   This  interface consists
  312.   largely of the dialog box: an intuitive and aesthetic means of  gathering
  313.   input from a user.  Dialog boxes are used  in professional, user-friendly
  314.   software, and  are present  in MacIntosh   software, Microsoft  Windows ,
  315.  
  316.   Hewlett-Packard's New Wave , the OS/2  Presentation Manager , and even in
  317.   the DOS 4.0 Shell .
  318.  
  319.  
  320.   Sophisticated, Elegant, & Powerful
  321.  
  322.   DiaLogic is a  sophisticated programming tool which allows  you to create
  323.   aesthetic text-based dialog boxes with a truly elegant mouse interface.  
  324.  
  325.   Generating a dialog box consists of these three steps:
  326.  
  327.      (1)    Creating a  dialog box  definition  file called  a  template
  328.             using the generic template we provide.
  329.  
  330.      (2)    Initializing a few variables.
  331.  
  332.      (3)    Calling the DiaLogic subprogram.
  333.  
  334.   Variations on how DiaLogic  is called from  a program provides the  added
  335.   power needed to create any kind of dialog box you could imagine:  from  a
  336.   simple error message with  a single ``OK'' button  to a full-blown  setup
  337.   screen which operates  in a polled mode!  To  illustrate this flexibility
  338.  
  339.         iv
  340.  
  341.  
  342.  
  343.  
  344.                                                                Introduction
  345.  
  346.   we have  written  a demonstration  program  which displays  and  explains
  347.   dialog boxes  as  it runs.   This  program appears  on your  distribution
  348.   diskette as DEMO.BAS.
  349.  
  350.   Practical
  351.  
  352.   DiaLogic's dialog boxes will  work and function very much like  those you
  353.   have possibly used in Microsoft's  QuickBASIC version 4.5, QuickC version
  354.   2.0, and Works .   The use of dialog boxes in your  programs will provide
  355.   these immediate practical benefits:
  356.  
  357.       *   Complex  user-query  screens will  not have  to  be tediously
  358.           coded  by you  in BASIC.   This  will give  you more  time to
  359.           spend on other aspects of your program.
  360.  
  361.       *   Your   dialog  boxes  will   add  an  aesthetic  and  highly-
  362.           professional  look-and-feel   to  your  own  programs   which
  363.           exactly corresponds to the Microsoft standard interface.
  364.  
  365.       *   End users will  immediately understand  the intuitive  dialog
  366.           box interface, especially if they are using a mouse.
  367.  
  368.   This manual is meant to  make the creation of dialog boxes  both easy and
  369.   enjoyable.
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.                                                 v
  388.  
  389.  
  390.  
  391.  
  392.   DiaLogic
  393.  
  394.   Compatibility
  395.  
  396.   System
  397.  
  398.   DiaLogic will run on IBM XT, AT, and PS/2-class machines and compatibles,
  399.   although you will  notice better performance on 16mhz or higher.  DOS 2.0
  400.   or above  is needed.  We recommend 640K of conventional memory to allow a
  401.   sufficient work space while in the QuickBASIC editor.
  402.  
  403.   QuickBASIC
  404.  
  405.   DiaLogic is available for users of  QuickBASIC, version 4.x.  If you  own
  406.   an earlier version we suggest that you contact  Microsoft for an upgrade.
  407.   The  current   release  of   QuickBASIC,  version   4.5,  provides   many
  408.   improvements over  prior versions.  Although DiaLogic is fully compatible
  409.   with version 4.0, we have used  version 4.5 during development and  refer
  410.   to some of its features throughout this manual.  One further note is that
  411.   some version-4.5 pull-down menu choices, although functionally identical,
  412.   have names which are slightly different from their 4.0  predecessors.  We
  413.   will be happy to help you if you need more information before trading up.
  414.  
  415.  
  416.   Using This Manual
  417.  
  418.   Intended Audience
  419.  
  420.   This  manual  assumes  very  little  knowledge  of  dialog  boxes  but  a
  421.   comfortable  understanding  of QuickBASIC.    We  have  not attempted  to
  422.   unnecessarily  duplicate  information  which  is  QuickBASIC-related  and
  423.   appears in the QuickBASIC  documentation.  We  do, however, provide  many
  424.   useful tips.
  425.  
  426.   Contents
  427.  
  428.   This manual  follows a  progression from  general terms  and concepts  to
  429.   specific applications.  Therefore, we recommend reading the entire manual
  430.   at least once.  Here's a summary of this manual's contents:
  431.  
  432.  
  433.  
  434.  
  435.  
  436.         vi
  437.  
  438.  
  439.  
  440.  
  441.                                                                Introduction
  442.  
  443.        *  Part I explains  how to install the  program and how to  make
  444.           it  available   from  within   the  QuickBASIC   editor  (the
  445.           environment).  
  446.  
  447.        *  Part II presents  an operational overview of  the product and
  448.           provides  detailed information  about all  dialog box-related
  449.           terms and concepts.
  450.  
  451.        *  Part  III  contains  information  about creating  dialog  box
  452.           templates -- special  files which contain information  needed
  453.           to define  a dialog  box.  We  present this  discussion in  a
  454.           tutorial-like style since constructing such  templates is the
  455.           most difficult part of DiaLogic.
  456.  
  457.        *  Part  IV explains how to  call DiaLogic  and explains all the
  458.           required prerequisite steps.
  459.  
  460.        *  Part V explains  compiling and  linking and provides  all the
  461.           required  steps for  creating  stand-alone .EXE  files  which
  462.           contain dialog boxes.
  463.  
  464.        *  Part  VI  addresses  more  advanced features  and  topics  of
  465.           DiaLogic  such  as  multi-tasking and  stacked  dialog boxes.
  466.           Several example programs are discussed in terms  of practical
  467.           programming considerations.
  468.  
  469.        *  Appendices  appear towards the end of this manual, and should
  470.           prove  very  helpful  once  you  begin  using   the  program.
  471.           Appendix A summarizes the template structure for  each dialog
  472.           box element.   Appendix B  offers ways  of reducing the  size
  473.           and making modifications to the DiaLogic module.  Appendix  C
  474.           is a troubleshooting section  which will  assist you in  case
  475.           of difficulty.   Appendix D gives a color  chart.  Appendix E
  476.           provides ASCII character charts.  
  477.  
  478.        *  A Glossary is provided for your convenience.
  479.  
  480.  
  481.  
  482.                                               vii
  483.  
  484.   Notational Conventions
  485.  
  486.   DiaLogic
  487.  
  488.   We  have used some variations in type style  mainly so that the manual is
  489.   more enjoyable to read.  The purpose for most type styles is clear (i.e.,
  490.   for topic headings,  computer text, etc.),  however there are a  few uses
  491.   which may require further explanation:
  492.  
  493.        *  All examples  of computer  input or  output are  printed in  a
  494.           fixed-spaced line printer font.  For instance, consider the DO
  495.           loop below:
  496.  
  497.             'pause for a key press
  498.             DO
  499.             LOOP UNTIL LEN(INKEY$)
  500.                .
  501.                .
  502.                .
  503.  
  504.        *  Notice also  the use of vertical ellipses to  convey that more
  505.           program instructions  may follow and  the use  of BASIC's  REM
  506.           symbol (') to present comments.
  507.  
  508.        *  Variable names  embedded in the  main text are often  printed
  509.           in  the line  printer font  when they  are mentioned  for the
  510.           first time in a discussion.  For example:
  511.  
  512.             ``The variable X% represents  an integer.  This means
  513.             that X% will occupy two bytes of memory.''
  514.  
  515.        *  The  first ``X%'' above is  easily discernable  as a variable
  516.           name.   To enhance readability we  will avoid excessive font-
  517.           changes (especially  to the  line printer font)  in the  main
  518.           text.
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.         viii
  531.  
  532.  
  533.  
  534.  
  535.                                                                Introduction
  536.  
  537.           Instances  when  the  computer  input  or  output   may  vary
  538.           (depending  on your  hardware, software,  etc.) are  shown in
  539.           italics.   For example,  the QuickBASIC Quick Library support
  540.           module  will have a slightly  different name depending on its
  541.           version  number.  We therefore would refer  to such a file as
  542.           in the example below:
  543.  
  544.             LINK PROGNAME.OBJ,,BQLB45 /Q
  545.  
  546.           Notice that  not only  is  ``45''  italicized, but  also  the
  547.           program name, which will vary, is italicized.
  548.  
  549.        *  In some examples  there may be optional features in a syntax.
  550.           These  features  will  be  shown  in  square  brackets.   For
  551.           example, the LET statement is optional in QuickBASIC:
  552.  
  553.             [LET ]A = 10
  554.  
  555.        *  There  are many  instances when  we will  speak of  an array,
  556.           usually  a TYPE array, and leave  its array subscripts empty.
  557.           For example:
  558.  
  559.             X().Row = 10
  560.  
  561.        *  The  above example is not  a valid  array assignment in BASIC
  562.           because  its  subscripts  are  missing.   Rather,  a  correct
  563.           syntax would be something like this:
  564.  
  565.             X(1, 5).Row = 10
  566.  
  567.        *  This would assign element  (1, 5) of the Row  element for the
  568.           X()  TYPE array  to 10.   We've  omitted subscripts  for many
  569.           examples  because the focus in  much of the manual  is on the
  570.           array  assignments and  not  on  the array  subscripts.    We
  571.           explain  the  correct use  of  the  subscripts in  Part  III:
  572.           Creating a Template and in Part IV: Generating a Dialog Box.
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.                                                ix
  580.  
  581.  
  582.  
  583.  
  584.   DiaLogic
  585.  
  586.        *  Keys on the  keyboard are represented in angle brackets.  For
  587.           example,  <F1> is the F1  function key;  <Enter> is the Enter
  588.           or Return key.   This is an  accepted convention but in  this
  589.           document there  may be  some confusion  since the dialog  box
  590.           element  called a command  button is similarly represented in
  591.           angle brackets.  When context  does not make the  distinction
  592.           clear, we have boldfaced the command button name:
  593.  
  594.             ``Pressing  <Enter>  will execute  the  <OK>  command
  595.             button.''
  596.  
  597.        *  Program lines  from an  include file are  enclosed in  double
  598.           angle brackets.  Consider this portion of a BASIC program:
  599.  
  600.             REDIM DB(2, 20) AS DialogType
  601.             REDIM LB(50) AS ListType
  602.             '$INCLUDE: 'TEMPLATENAME.DB'
  603.             <<DB(Level%, 1).Code = 1>>
  604.             <<DB(Level%, 2).Y = 0>>
  605.             <<DB(Level%, 3).X = 0>>
  606.                .
  607.                .
  608.                .
  609.  
  610.        *  The    DB()   array   assignments   above   appear   in   the
  611.           TEMPLATENAME.DB   include  file:   they  are  not  explicitly
  612.           present in this BASIC program.
  613.  
  614.        *  All BASIC key words and all DOS file names  are written in
  615.           uppercase letters.
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.         x
  629.  
  630.  
  631.  
  632.  
  633.                                                                Introduction
  634.  
  635.   Technical Support
  636.  
  637.   We always welcome  your calls.   However, before you  call for  technical
  638.   support please check Appendix C: Troubleshooting, to see if your question
  639.   is discussed.  If the problem persists you may call us at (703) 528-1505,
  640.   between  9:00 a.m.  and 5:00  p.m. EST,  Monday through  Friday.   Please
  641.   gather as  much detail as possible about the problem before you call.  In
  642.   some  extenuating  circumstances we  may  ask to  examine  the particular
  643.   dialog box template and calling syntax being used in order to assist you.
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.                                                xi
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.                                    DiaLogic
  693.  
  694.  
  695.                                     PART I
  696.                                GETTING STARTED
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.                                                             Getting Started
  704.  
  705.   Quick Start
  706.  
  707.   This manual covers  many important topics that  you will need to  know in
  708.   order to  use DiaLogic effectively.   However, if  you are familiar  with
  709.   BASIC programming and want to be able  to create dialog boxes right away,
  710.   simply start QuickBASIC by loading both DIALOGIC.BAS and the DIALOGIC.QLB
  711.   Quick Library like this:
  712.  
  713.      QB DIALOGIC.BAS /L DIALOGIC.QLB
  714.  
  715.   This syntax  assumes both  DIALOGIC files are  in the  current directory.
  716.   Once BASIC has started you will be able to create dialog boxes.  Although
  717.   this is all you need to do  please be aware that the calling requirements
  718.   of DiaLogic are extensive.  Therefore we strongly recommend that you read
  719.   this entire manual before using the program.
  720.  
  721.  
  722.   Things To Do First
  723.  
  724.   The Demo
  725.  
  726.   Before we get started you should first have a solid understanding of what
  727.   dialog  boxes  are and  how they  function.   For  this reason  we highly
  728.   recommend  that you run  the demo  we have  supplied on  the distribution
  729.   diskette.  To run the demo, start QuickBASIC and load the  DiaLogic Quick
  730.   Library like this:
  731.  
  732.      QB /L DIALOGIC
  733.  
  734.   Once QuickBASIC starts you may load the file DEMO.BAS using the File Open
  735.   pull-down menu option (you must  use the open option in order to load the
  736.   demo correctly).  Then press <Shift><F5> to start the program.
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.                                                 3
  748.  
  749.  
  750.  
  751.  
  752.   DiaLogic
  753.  
  754.   Although  the demo  in no way  is meant  to replace  the manual,  it does
  755.   provide a means  for you to actually interact with dialog boxes.  We feel
  756.   that once you  have read and understand  the information in the  demo you
  757.   should be comfortable with dialog box terminology.
  758.  
  759.   README
  760.  
  761.   Additions or changes to this manual will  appear in a file called README.
  762.   Simply enter the following DOS command to peruse it:
  763.  
  764.      TYPE README
  765.  
  766.  
  767.   Installation
  768.  
  769.   What's On The Diskette
  770.  
  771.   The following files should be on your distribution diskette:
  772.  
  773.  
  774.      File Name       Description
  775.  
  776.      DEMO.BAS        Our demonstration program.  Highly-suggested
  777.                      viewing material!
  778.      DIALOGIC.BAS    DiaLogic's BASIC source code.
  779.      DIALOGIC.QLB    Assembler Quick Library for use when loading
  780.                      DIALOGIC.BAS into the environment.
  781.      DIALOGIC.LIB    Assembler Library for use when linking.
  782.      DIALOGIC.BI     BASIC include file which contains DiaLogic's DECLARE
  783.                      statements and necessary TYPE declarations.
  784.      EXAMPLE?.BAS    BASIC example programs.
  785.      README          A text file which, if present, contains update notes
  786.                      for DiaLogic.
  787.      TEMPLATE.DOC    DiaLogic's generic dialog box template.
  788.      *.DB            Dialog box template include files.
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.         4
  797.  
  798.  
  799.  
  800.  
  801.                                                             Getting Started
  802.  
  803.   Copying and Backing Up
  804.  
  805.   Before you start to  use the program you should first make  a copy of the
  806.   original diskette and then work with the copy.  We know we didn't have to
  807.   tell  you  this; but  reminding  you  could  prevent a  very  frustrating
  808.   situation should  your distribution diskette become damaged.  For optimum
  809.   performance when  using DiaLogic  we recommend copying  the files  onto a
  810.   fixed disk.
  811.  
  812.   Loading the Source Code
  813.  
  814.   DiaLogic was  written in QuickBASIC  and uses assembly  language routines
  815.   when possible  to  produce the  fastest  performance and  smallest  code.
  816.   Future releases of DiaLogic will be further optimized and will  take even
  817.   greater advantage  of low-level  languages.   Since  DiaLogic depends  on
  818.   external  assembler  routines,   you  should   make  them  available   to
  819.   QuickBASIC.    We   have  provided  you  with  a   Quick  Library  called
  820.   DIALOGIC.QLB which contains  only assembler routines.  You  may load this
  821.   library like this:
  822.  
  823.      QB /L DIALOGIC
  824.  
  825.   DIALOGIC.BAS may now be loaded into the QuickBASIC environment using  the
  826.   File Load pull-down menu option.
  827.  
  828.   At some point you may wish to compile DIALOGIC and create a Quick Library
  829.   which contains  DIALOGIC.BAS  and  the  assembler routines  on  which  it
  830.   depends.   We will  discuss this process  in Part V:  Creating Standalone
  831.   Programs.
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.                                                 5
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.                                                      Dialog Box Basics
  848.  
  849.      Overview of DiaLogic's Operation
  850.  
  851.      This manual is  organized to  provide very detailed  instructions
  852.      for  implementing dialog boxes.  We'd like you to get an overview
  853.      of how  dialog boxes  will be  used by  your  programs before  we
  854.      present  the detailed  aspects.   This  should  provide you  with
  855.      additional background information before reading  the rest of the
  856.      manual.
  857.  
  858.  
  859.      Arguments in the Call
  860.  
  861.      Five arguments must be passed  for every dialog box.  We  mention
  862.      these arguments for overview purposes only:
  863.  
  864.  
  865.  
  866.      Argument
  867.        Name     Description
  868.  
  869.        DB()     The dialog box definition
  870.        LB()     The contents of all list boxes
  871.        Focus%   The element on which the cursor rests
  872.        Action%  The manner in which the dialog box is to operate
  873.        Ky$      The most recent keystroke captured
  874.  
  875.  
  876.      The DB() TYPE  array contains all information needed  to create a
  877.      dialog box.  The LB() TYPE array stores  all list box items for a
  878.      single dialog box.  The integer Focus% specifies on which  dialog
  879.      box element the cursor rests.  The integer Action% determines the
  880.      pre- and post-operative behavior of a dialog box.  And, last, the
  881.      conventional  (variable-length) string  Ky$  enables the  calling
  882.      program to access the most recent keystroke captured by DiaLogic.
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.                                                                      9
  892.  
  893.  
  894.  
  895.  
  896.      DiaLogic
  897.  
  898.      To further clarify things, please realize that the DB() array  is
  899.      used like a set  of ``instructions'' which  directs how a  dialog
  900.      box will  be displayed.   For instance, the  DB() array is  why a
  901.      Search dialog box looks  different from a  File Load dialog  box.
  902.      The argument Action% determines how the dialog box will  operate.
  903.      For example, one type of operation causes full program control to
  904.      remain with the dialog  box until the  user has completed  input;
  905.      another allows the calling  program to regain control  before the
  906.      dialog box accepts any user input.  
  907.  
  908.      After using a  dialog box the calling program  may determine what
  909.      type of input  the user has entered by examining  portions of the
  910.      DB() array which correspond to the item of interest.  Each dialog
  911.      box element has  a one-to-one correspondence to  elements defined
  912.      in the DB() array.   Additional information  is available to  the
  913.      calling program by examining Focus% and Ky$.  The LB() array only
  914.      provides information to DiaLogic:  it does not return  any useful
  915.      information.
  916.  
  917.      Don't  be  concerned if  the  purpose  of  each argument  is  not
  918.      understood from our brief overview:  all will be fully explained.
  919.  
  920.  
  921.      The Use of Ambiguous Variable Names
  922.  
  923.      In the  interest  of making  the  calling syntax  as  compact  as
  924.      possible we have made use of a single TYPE array to  hold all the
  925.      information  needed  to  display  a  dialog box.    Occasionally,
  926.      however, we have  used a variable  in the  TYPE definition for  a
  927.      purpose which does  not seem to correspond to its name.  The best
  928.      way to understand this is to present an example.
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.      10
  941.  
  942.  
  943.  
  944.  
  945.                                                      Dialog Box Basics
  946.  
  947.  
  948.  
  949.        Note:
  950.           The  DrawIt  subprogram is  fictitious and  is  used for
  951.           discussion  purposes  only.   It  is  not included  with
  952.           DiaLogic.
  953.  
  954.  
  955.  
  956.      Suppose  we  want to  create a  subprogram, called  DrawIt, which
  957.      either draws a  circle or rectangle, and  then adds color  to the
  958.      figure.  We could decide to pass all the information needed  in a
  959.      single  user-defined  TYPE.    Our   TYPE  declaration  may  look
  960.      something like this:
  961.  
  962.        TYPE GeometricShape
  963.           Code = INTEGER    '1 = rectangle, 2 = circle
  964.           Wide = INTEGER    'width (or diameter)
  965.           High = INTEGER    'height
  966.           Colr = INTEGER    'inside color
  967.        END TYPE
  968.        DIM Shape AS GeometricShape
  969.  
  970.      If we  wanted to draw a 5X7 rectangle colored blue we may use the
  971.      following variables from our user-defined TYPE:
  972.  
  973.        Shape.Code = 1       'for a rectangle
  974.        Shape.Wide = 5       'width of the rectangle
  975.        Shape.High = 7       'height of the rectangle
  976.        Shape.Colr = 1       'inside color of the rectangle
  977.        CALL DrawIt(Shape)
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.                                                                     11
  990.  
  991.  
  992.  
  993.  
  994.      DiaLogic
  995.  
  996.      This would  draw a rectangle which is 5  units across and 7 units
  997.      high.  Now, let's say we want to draw a circle.  We could use the
  998.      following:
  999.  
  1000.        Shape.Code = 2       'for a circle
  1001.        Shape.Wide = 5       'the diameter of the circle
  1002.        Shape.High = 0       'not used for circles
  1003.        Shape.Colr = 1       'inside color of the circle
  1004.        CALL DrawIt(Shape)
  1005.  
  1006.      Notice  that  Shape.Wide  now  refers  to  a  diameter  and  that
  1007.      Shape.High  is not  even  used for  the circle!    If the  DrawIt
  1008.      program  is  ``smart'' it  will  inspect Shape.Code  to determine
  1009.      which elements of the  Shape TYPE array it should use.   In order
  1010.      to draw  the rectangle  it would require  the width,  height, and
  1011.      color of the object.  But to draw the circle, only  the ``width''
  1012.      (i.e., the diameter) and the color  are needed.  Thus, we've used
  1013.      Shape.Wide  to hold either the rectangle's  width or the circle's
  1014.      diameter.
  1015.  
  1016.      Our rudimentary example explains how a TYPE variable name can  be
  1017.      called something which is inconsistent with its function.  Please
  1018.      realize that this ambiguity could be avoided by creating an extra
  1019.      variable  in the TYPE  called Diam, for  the diameter.   The TYPE
  1020.      declaration would then look like this:
  1021.  
  1022.        TYPE GeometricShape
  1023.           Code = INTEGER    '1 = rectangle, 2 = circle
  1024.           Wide = INTEGER    'width
  1025.           High = INTEGER    'height
  1026.           Diam = INTEGER    'diameter
  1027.           Colr = INTEGER    'inside color
  1028.        END TYPE
  1029.        DIM Shape AS GeometricShape
  1030.  
  1031.      The addition of  Diam is wasteful  because it adds  2 bytes  (the
  1032.      size of an integer) to the TYPE definition.  Further, 4 bytes are
  1033.      wasted when a  circle is defined since  both width (2  bytes) and
  1034.      height (2 bytes) would not be used.
  1035.  
  1036.  
  1037.  
  1038.      12
  1039.  
  1040.  
  1041.  
  1042.  
  1043.                                                      Dialog Box Basics
  1044.  
  1045.      One solution to  such variable naming problems is  to use generic
  1046.      nomenclature.  Thus, we could have defined Wide as Across,  Size,
  1047.      or something more general, such as NumberOne.  This last example,
  1048.      NumberOne, is  fitting:  it not  only  is generic,  but  also  it
  1049.      conveys  that  a number  is  expected  and not  a  string.   When
  1050.      appropriate  we've  used similar  generic  nomenclature for  TYPE
  1051.      variable names which are used for different purposes.  In fact we
  1052.      make use of  the names NumberOne  and NumberTwo!   In a few  very
  1053.      rare instances you may encounter variable names which seem really
  1054.      inappropriate, but keep in mind that this was done ultimately  to
  1055.      save a few bytes.
  1056.  
  1057.      You will learn that DiaLogic has a TYPE  definition which is more
  1058.      complex  than  the one  used  in our  DrawIt  example.   In fact,
  1059.      DiaLogic's  TYPE   arrays  are  not  only  larger  but  also  are
  1060.      dimensioned.    A TYPE  array  is  dimensioned using  BASIC  code
  1061.      similar to:
  1062.  
  1063.        DIM Shape(20) AS GeometricShape
  1064.  
  1065.      If we  had done this  we could have  passed up to  20 pre-defined
  1066.      shapes in a  single call to DrawIt.   The ability to pass  a very
  1067.      large amount of information in a single variable is indeed a most
  1068.      powerful feature of dimensioned TYPE arrays.
  1069.  
  1070.  
  1071.      Terms & Concepts 
  1072.  
  1073.      Since dialog boxes are associated with several terms which may be
  1074.      new to you, understanding this section is essential.  
  1075.  
  1076.      The Elements
  1077.  
  1078.      Dialog boxes are comprised  of dialog box  elements (DBEs).   The
  1079.      eight  DBEs are  summarized in  Figure  2.   You should  acquaint
  1080.      yourself not only with their names but also with their associated
  1081.      numbers.  The numbers are important, for they describe a specific
  1082.      DBE in terms of a numerical code:
  1083.  
  1084.  
  1085.  
  1086.  
  1087.                                                                     13
  1088.  
  1089.  
  1090.  
  1091.  
  1092.      DiaLogic
  1093.  
  1094.        Code  Description
  1095.  
  1096.        1     Window
  1097.        2     Text Box
  1098.        3     List Box
  1099.        4     Check Box
  1100.        5     Option Buttons
  1101.        6     Smart Label
  1102.        7     Command Button
  1103.        8     Group Box
  1104.  
  1105.  
  1106.      Beginning  on  page  27,  the  section called  Understanding  the
  1107.      Elements explains each DBE in much greater detail.
  1108.  
  1109.      The Input Focus
  1110.  
  1111.      The DBE  on which  the cursor  rests is  said to  have the  input
  1112.      focus, and only the DBEs designated with a happy face in Figure 2
  1113.      may receive it.  The input focus is important because it allows a
  1114.      specific dialog  box  element, such  as  a text  box,  to  accept
  1115.      information from the user.
  1116.  
  1117.      The input focus is transferred from one DBE to another in several
  1118.      ways:
  1119.  
  1120.        *  Using the  <Tab> or  <Shift><Tab> keys:  These keys  will
  1121.           access each DBE  in a pre-defined Sequence.   <Tab>  will
  1122.           access   dialog  box  elements  in  one  direction  while
  1123.           <Shift><Tab> will access them in  the opposite direction.
  1124.  
  1125.  
  1126.        *  Using an Alt-key: Alt-keys, explained next, will directly
  1127.           access a DBE by immediately transferring the input focus.
  1128.  
  1129.        *  Using the mouse: Placing the mouse cursor over a  DBE and
  1130.           pressing a mouse  button will  transfer the  input focus.
  1131.           This mouse maneuver  is commonly referred  to as clicking
  1132.           on an option.
  1133.  
  1134.  
  1135.  
  1136.      14
  1137.  
  1138.  
  1139.  
  1140.  
  1141.                                                      Dialog Box Basics
  1142.  
  1143.      Alt-keys
  1144.  
  1145.      When the <Alt> key is pressed certain words will suddenly  reveal
  1146.      a highlighted  character.   This character is  referred to  as an
  1147.      Alt-key.  To  access a DBE which has an Alt-key character, simply
  1148.      hold down the <Alt> key and  type the highlighted character.  You
  1149.      will notice that  the input focus is  transferred.  If there  are
  1150.      different DBEs with the same Alt-key, then each will be  accessed
  1151.      in turn.
  1152.  
  1153.      Alt-keys  provide  keyboard users  with  the ability  to directly
  1154.      access a dialog box element.  They may be defined for the letters
  1155.      ``A'' through ``Z'' and the numbers 0 through 9 only.
  1156.  
  1157.      If the input focus is on  a dialog box element other than a  text
  1158.      box or list box then an  Alt-key may be pressed unaccompanied  by
  1159.      the <Alt> key.  For example, if the input focus is on a check box
  1160.      and you wish to transfer it  to an option button with an  Alt-key
  1161.      F,  then you may press either  <Alt>F or simply F.   On the other
  1162.      hand, if the input focus  were on a text box rather than  a check
  1163.      box then typing  F, alone, would cause the letter to be placed in
  1164.      the text  box.  In this instance, then, you  may use only the key
  1165.      combination <Alt>F.
  1166.  
  1167.  
  1168.      The Tilde (~) Character
  1169.  
  1170.      The tilde character is used by DiaLogic in two ways:
  1171.  
  1172.        (1)   To signify  that  the following  character  is  to
  1173.              become an Alt-key.  For example:
  1174.  
  1175.              DB().Text = "Match ~Upper/Lower Case"
  1176.  
  1177.           The above assignment  specifies a text label which  has a
  1178.           tilde  before the  ``U'' character in  ``Upper'', thereby
  1179.           creating an Alt-key.   Thus,  when <Alt> is  pressed, the
  1180.           letter ``U'' will be highlighted.  The tilde is a special
  1181.           symbol to DiaLogic  and, therefore,  is not  printed even
  1182.           though it  appears in the string.  Notice  that, for text
  1183.           labels, the tilde may be embedded anywhere in the string.
  1184.  
  1185.  
  1186.  
  1187.                                                                     15
  1188.  
  1189.  
  1190.  
  1191.  
  1192.      DiaLogic
  1193.  
  1194.        (2)   To  signify  that  the  following  text  is to  be
  1195.              printed in a different color.  For example:
  1196.  
  1197.              LB(1).Text = "Item One"
  1198.              LB(2).Text = "Item Two"
  1199.              LB(3).Text = "~Item Three"
  1200.                 .
  1201.                 .
  1202.                 .
  1203.  
  1204.  
  1205.  
  1206.           These  assignments  begin to  fill the  LB()  TYPE array
  1207.           with  text.  LB() is  a special  array you'll learn more
  1208.           about, but for now you  should know that a list  box can
  1209.           print  each array item in one of  two colors.  These two
  1210.           colors  are  referred  as  the  primary  color  and  the
  1211.           secondary  color.    Observe  in our  example  that  the
  1212.           string  held by  the third  LB()  element has  a leading
  1213.           tilde.  ``Item Three'', therefore,  is displayed in  the
  1214.           secondary color  simply because  it has a  tilde as  its
  1215.           first character.   The  other two items will  be printed
  1216.           in the primary  color of the list  box.  Notice that  in
  1217.           this instance, unlike our text label example,  the tilde
  1218.           must be at the very beginning of the string.
  1219.  
  1220.      To summarize, the  creation of an Alt-key  is a simple  matter of
  1221.      inserting a tilde immediately before the character you wish to be
  1222.      highlighted in a text string.  In this text:
  1223.  
  1224.        DB().Text = "File ~Name:"
  1225.  
  1226.      the  N will  be displayed as  an Alt-key  when the dialog  box is
  1227.      activated.  Thus,  pressing <Alt>N will transfer  the input focus
  1228.      to the  dialog box  element associated  with, or  linked to,  the
  1229.      label File Name.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.      16
  1237.  
  1238.  
  1239.  
  1240.  
  1241.                                                      Dialog Box Basics
  1242.  
  1243.      The tilde serves a different purpose for the elements in the list
  1244.      box array.  In a list box two colors (also called attributes) may
  1245.      be defined.   The  primary color  is the  color of  all list  box
  1246.      elements  which do not have a leading tilde;  the secondary color
  1247.      is used for all elements which have a leading tilde.
  1248.  
  1249.      The DB() Array
  1250.  
  1251.      A  single array  holds all  the  information needed  to define  a
  1252.      dialog box.   We've called this  array DB, short  for Dialog Box.
  1253.      DB() is a two-dimension TYPE array.  The size  of the TYPE is 256
  1254.      bytes.  The first dimension, the Level, refers to a single dialog
  1255.      box and it allows the DB() array to  store multiple dialog boxes.
  1256.      Although all dialog boxes may be generated using a Level of 1, it
  1257.      is  necessary to  use greater  Levels if dialog  boxes are  to be
  1258.      stacked on the  screen.  The use of different Levels is discussed
  1259.      in greater detail in Part VI: Advanced Topics.
  1260.  
  1261.      The second dimension of the DB() TYPE array refers  to the dialog
  1262.      box  element Sequence.   As  mentioned  earlier on  page 14,  the
  1263.      Sequence  refers to  the order in  which the <Tab>  key will pass
  1264.      across the DBEs in  a dialog box.   For example, in  QuickBASIC's
  1265.      error messages there is generally a main list box containing  the
  1266.      error text, and two command  buttons, <OK> and <Help>.  When  the
  1267.      <Tab> key  is pressed, the input focus  travels from the list box
  1268.      to the  <OK> button,  and then  to the  <Help> button.   In  this
  1269.      example, then, the  list box has a  Sequence which is equal  to 2
  1270.      (not an error), the <OK> button is 3, and the <Help> button is 4.
  1271.      An  important rule  to remember  is  that the  dialog box  window
  1272.      always has a Sequence which is equal to 1.  Further, no two  DBEs
  1273.      in a dialog box may have equal Sequence numbers.
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.                                                                     17
  1286.  
  1287.  
  1288.  
  1289.  
  1290.      DiaLogic
  1291.  
  1292.      Thus, dimensioning  the DB()  array is based  on how  many dialog
  1293.      boxes you will have  stacked on the  screen (the maximum  Level),
  1294.      and how  many  DBEs each  dialog  box may  contain  (the  maximum
  1295.      Sequence).  The statements
  1296.  
  1297.        '$DYNAMIC
  1298.        Level% = 2           'set the Level (shown for clarity)
  1299.        Sequence% = 15       'set the Sequence (shown for clarity)
  1300.        REDIM DB(Level%, Sequence%) AS DialogType
  1301.  
  1302.      show  that memory  is being  reserved for  a maximum  Level  of 2
  1303.      stacked dialog boxes;  each dialog  box may have a maximum of  15
  1304.      dialog box elements.  The TYPE structure for DialogType is  shown
  1305.      next:
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.      18
  1335.  
  1336.  
  1337.  
  1338.  
  1339.                                                      Dialog Box Basics
  1340.  
  1341.        TYPE DialogType 
  1342.              BorderType AS INTEGER 
  1343.              Code AS INTEGER 
  1344.              Default AS INTEGER 
  1345.              Height AS INTEGER 
  1346.              ItemLength AS INTEGER 
  1347.              KeyColor AS INTEGER 
  1348.              Link AS INTEGER 
  1349.              NumberOne AS INTEGER 
  1350.              NumberTwo AS INTEGER 
  1351.              PrimaryColor AS INTEGER 
  1352.              SecondaryColor AS INTEGER 
  1353.              SelectedColor AS INTEGER 
  1354.              StarColor AS INTEGER 
  1355.              Text AS STRING * 82         'used to make TYPE  256 bytes
  1356.              TextColor AS INTEGER 
  1357.              TextString AS STRING * 134  'used to make TYPE  256 bytes
  1358.              total
  1359.              TextX AS INTEGER 
  1360.              TextY AS INTEGER 
  1361.              Wdth AS INTEGER 
  1362.              WindowColor AS INTEGER 
  1363.              X AS INTEGER 
  1364.              Y AS INTEGER 
  1365.        END TYPE 
  1366.  
  1367.  
  1368.      The LB() Array
  1369.  
  1370.      LB() is  a one-dimension  TYPE array defined  as a  single fixed-
  1371.      length string.  The length of the entire TYPE is 256 which, here,
  1372.      is also the length of each LB() array element.
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.                                                                     19
  1383.  
  1384.  
  1385.  
  1386.  
  1387.      DiaLogic
  1388.  
  1389.      The  LB() array holds  the items which  will be used  by all list
  1390.      boxes in a  dialog box.  This  is possible because each  list box
  1391.      accesses a specific range of LB()  array elements.  The use of  a
  1392.      single array not only simplifies the DiaLogic calling syntax, but
  1393.      also allows  the LB()  array  to be  partitioned into  functional
  1394.      units.  For  example, if you are constructing a dialog box to set
  1395.      up a printer you  may wish to  reserve LB() elements  1 to 5  for
  1396.      available output ports;  elements 6 to  15 for available  printer
  1397.      names; and elements 16  to 30 for  available printer fonts.   You
  1398.      may then create three separate list boxes on this dialog box: the
  1399.      first would access  LB() elements 1 through 5 and would therefore
  1400.      display the output ports; the second would access LB() elements 6
  1401.      through  15, and would  present available printer  names; and the
  1402.      third would access LB() elements 16 through 30, which would  show
  1403.      all available  printer fonts.   Any number of  list boxes may  be
  1404.      displayed, and they  are particularly suited for  presenting much
  1405.      information.
  1406.  
  1407.      The ListType TYPE declaration looks like this:
  1408.  
  1409.        TYPE ListType 
  1410.           Text AS STRING * 256 
  1411.        END TYPE
  1412.  
  1413.      The LB() array then is dimensioned like this:
  1414.  
  1415.        '$DYNAMIC
  1416.        REDIM LB(30) AS ListType
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.      20
  1432.  
  1433.  
  1434.  
  1435.  
  1436.                                                      Dialog Box Basics
  1437.  
  1438.      The Dialog Box Template
  1439.  
  1440.      The activation of a dialog box relies on instructions supplied by
  1441.      a template.   These instructions, which consist primarily of DB()
  1442.      array  assignments, provide  information  such  as the  position,
  1443.      size, and  color  of  each  dialog  box  element.    Since  these
  1444.      assignments may become quite lengthy, templates are often kept in
  1445.      an include  file so that  they may  be imported easily  into many
  1446.      different  programs  and so  that  they  do not  clutter  program
  1447.      listings.  DiaLogic's template include files are distinguished by
  1448.      their .DB extension.  We have provided you with several templates
  1449.      which  are  used  by  the  demo  and  example  programs  on  your
  1450.      distribution diskette.  Figure 3 depicts an excerpt:
  1451.  
  1452.      DB(Level%, 1).Code = 1
  1453.      DB(Level%, 1).Y = 0  
  1454.      DB(Level%, 1).X = 0  
  1455.      DB(Level%, 1).Height = 12
  1456.      DB(Level%, 1).Wdth = 60  
  1457.      DB(Level%, 1).BorderType = -1 
  1458.      DB(Level%, 1).PrimaryColor = -112
  1459.      DB(Level%, 1).WindowColor = -112 
  1460.      DB(Level%, 1).Text = "Find"      
  1461.      DB(Level%, 1).TextColor = 112
  1462.      DB(Level%, 1).SecondaryColor = 112
  1463.      DB(Level%, 1).NumberOne = 25
  1464.  
  1465.      DB(Level%, 2).Code = 2            
  1466.      DB(Level%, 2).Y = 2               
  1467.      DB(Level%, 2).X = 14              
  1468.                 .
  1469.                 .
  1470.                 .
  1471.  
  1472.      Constructing a template is unfortunately the most tedious process
  1473.      in creating  a dialog box.   However, the  QuickBASIC environment
  1474.      greatly simplifies the process by providing the means to transfer
  1475.      text  from one  file  to  another.   This  process  is  called  a
  1476.      copy & paste operation.
  1477.  
  1478.  
  1479.  
  1480.                                                                     21
  1481.  
  1482.  
  1483.  
  1484.  
  1485.      DiaLogic
  1486.  
  1487.      To assist you, we have created a generic template which  consists
  1488.      of  just the left  side of the array  assignments for each dialog
  1489.      box element.   A sample line  from the generic template  would be
  1490.      something like this:
  1491.  
  1492.        DB(Level%, 1).Code =
  1493.  
  1494.      The generic template  is loaded as  a document into  QuickBASIC's
  1495.      environment so that  you may select those equates  which you need
  1496.      in order  to construct your custom template.  For example, if you
  1497.      decide you want a  command button in a dialog box  you could copy
  1498.      all equates for  a command button and then paste them to your own
  1499.      template.    This  process  of  copying  & pasting  is  described
  1500.      completely in Part III: Creating a Template.
  1501.  
  1502.  
  1503.        Note:
  1504.           The  copy  & paste  procedure is  suggested so  that you
  1505.           don't  have to manually  enter all the equate statements
  1506.           each time you wish to construct a dialog box.   Once you
  1507.           become   comfortable  with   the  procedure,  you  shall
  1508.           discover  that transferring  data between  files in  the
  1509.           environment is useful, convenient, and expeditious.
  1510.  
  1511.  
  1512.  
  1513.      Include Files
  1514.  
  1515.      Include files are loaded at  compile time by QuickBASIC when  the
  1516.      '$INCLUDE metacommand is encountered.   For example, consider the
  1517.      following statement:
  1518.  
  1519.        '$INCLUDE: 'SAMPLE.DB'
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.      22
  1530.  
  1531.  
  1532.  
  1533.  
  1534.                                                      Dialog Box Basics
  1535.  
  1536.      This  instruction  causes  QuickBASIC  to  load and  compile  the
  1537.      contents of  the file  SAMPLE.DB.   Notice two  things about  the
  1538.      statement:  there  is a leading REM and the file name is enclosed
  1539.      in single quotes.  A REM symbol (`) followed by a dollar sign  on
  1540.      the left margin usually tells QuickBASIC to expect a metacommand.
  1541.      Metacommands  are  special  commands  which  are  interpreted  at
  1542.      compile time: they are not considered part of the BASIC  language
  1543.      but, rather, are compiler-specific.
  1544.  
  1545.      There are three  other considerations when specifying  an include
  1546.      file.    First,  the file  in  quotes  must  exist  and  must  be
  1547.      available.  To make a file available it may be necessary to use a
  1548.      full directory  path along  with your  file name.   Consider  the
  1549.      following:
  1550.  
  1551.        '$INCLUDE: 'C:\QB4\INCLUDE\TEMPLATENAME.DB'
  1552.  
  1553.      This statement is similar to our previous example.  However, this
  1554.      time we have told QuickBASIC to use the .DB file on  the C: drive
  1555.      and  in the  \QB4\INCLUDE\ path.   An  alternative  to explicitly
  1556.      specifying the file-name path, like above, is to use the  Options
  1557.      Set Path... pull-down menu  option.  This  feature allows you  to
  1558.      specify a path which QuickBASIC should  use in the event that the
  1559.      specified include file is not  in the current directory.  If  you
  1560.      plan to set an include path in QuickBASIC then you should  omit a
  1561.      path specification when using the include metacommand.
  1562.  
  1563.      Second, the  include file  must have ``compilable''  code in  it.
  1564.      Once QuickBASIC reads an  include file it  will conduct the  same
  1565.      syntax checking  that  it performs  on  the rest  of  a  program.
  1566.      Therefore, insure that include files  consist of valid QuickBASIC
  1567.      program code.
  1568.  
  1569.      Third, when you are in the environment you may need to inspect an
  1570.      include  file  by using  the View  Included Lines  pull-down menu
  1571.      option.  This  option makes visible the contents  of each include
  1572.      file.  If you wish to edit an include file you should first place
  1573.      the  cursor on the line  containing the '$INCLUDE statement, then
  1574.      use the View Included File pull-down menu option.
  1575.  
  1576.  
  1577.  
  1578.                                                                     23
  1579.  
  1580.  
  1581.  
  1582.  
  1583.      DiaLogic
  1584.  
  1585.      DB() Variable Values
  1586.  
  1587.      The following  features are used  when assigning elements  to the
  1588.      DB() array when constructing  your template.   Keep in mind  that
  1589.      DiaLogic does not verify the values passed to it.  Therefore, pay
  1590.      particular  attention to  the  type  and  range  of  values  each
  1591.      variable may  accept.   For example,  in our  upcoming discussion
  1592.      concerning the  use  of color,  we  mention that  only  values  0
  1593.      through 7 should be  used for the  background attribute.   Values
  1594.      beyond this range should  not be used  and may cause  undesirable
  1595.      results.
  1596.  
  1597.      Color
  1598.  
  1599.      Colors are generally  described using  two terms: foreground  and
  1600.      background.  A  suitable analogy is to think of the foreground as
  1601.      the color of the  ``ink'' and the background as the  color of the
  1602.      ``paper''.  Although QuickBASIC's COLOR command allows foreground
  1603.      and background colors to be specified separately, the color of  a
  1604.      character on the screen in text mode is represented internally as
  1605.      a single byte.   This 8-bit byte  is comprised of 3  bits for the
  1606.      foreground color, 3 bits  for the background color, 1 bit for the
  1607.      brightness of the foreground color, and 1 bit for blinking.
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.      24
  1628.  
  1629.  
  1630.  
  1631.  
  1632.                                                      Dialog Box Basics
  1633.  
  1634.      The figure shown  next presents most of the  information you need
  1635.      to know  in  order to  use  color.   Please  try  to  familiarize
  1636.      yourself with the  8 colors (0 through 7)  available by different
  1637.      combinations of the 3 color bits:
  1638.  
  1639.           Value      Color
  1640.  
  1641.              0          Black
  1642.              1          Blue
  1643.              2          Green
  1644.              3          Cyan
  1645.              4          Red
  1646.              5          Magenta
  1647.              6          Brown
  1648.              7          White
  1649.  
  1650.      NOTES:
  1651.      Foreground Colors:
  1652.        Add 8 to above value for a bright color.
  1653.        Add 16 to a color for blinking.
  1654.      Background Colors:
  1655.        Use only values 0 through 7.
  1656.  
  1657.  
  1658.      When you decide to use a color, always choose a  background value
  1659.      between 0 and 7.  
  1660.  
  1661.      The allowable range for the foreground color is between 0 and 31.
  1662.      However, the  process of  selecting a foreground  color is  a bit
  1663.      more  complex.   First,  select a  color value  between 0  and 7.
  1664.      Second, if you want a bright color then add 8 to foreground value
  1665.      you  chose.   Once the brightness  is determined you  will have a
  1666.      foreground  color between  0 and  15.   Third, if  you  want this
  1667.      foreground color to blink, add 16 to its value.
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.                                                                     25
  1677.  
  1678.  
  1679.  
  1680.  
  1681.      DiaLogic
  1682.  
  1683.      Once  you have selected both foreground and background colors you
  1684.      may combine them into one byte as follows  (FG is the foreground;
  1685.      BG is the background):
  1686.  
  1687.        Colr% = (FG AND 16) * 8 + ((BG AND 7)* 16) + (FG AND 15)
  1688.  
  1689.      The previous formula  will insure that illegal  background values
  1690.      are trapped and it provides for a flashing foreground.  An easier
  1691.      formula follows, but please realize that it will not allow for  a
  1692.      flashing foreground (which is  rarely used in  a dialog box)  and
  1693.      you must pass to it a valid background color:
  1694.  
  1695.        Colr% = FG + 16 * BG
  1696.  
  1697.      If you  have a monochrome  type of display  it is best  to choose
  1698.      highly-contrasted combinations for the foreground and background:
  1699.      bright white  on black is  best.   Please see Appendix  D: Dialog
  1700.      Software Color Chart for a handy reference table.
  1701.  
  1702.      Borders
  1703.  
  1704.      All border types are specified by using a single number.   In all
  1705.      dialog box elements which  allow a border  style, simply use  the
  1706.      number below  which  is enclosed  by  the border  style  of  your
  1707.      choice:
  1708.  
  1709.                       No border
  1710.               0
  1711.  
  1712.  
  1713.                       Single outline
  1714.               1
  1715.  
  1716.  
  1717.                       Double outline
  1718.               2
  1719.  
  1720.  
  1721.                       Single across, double down
  1722.               3
  1723.  
  1724.  
  1725.                       Double across, single down
  1726.               4
  1727.  
  1728.  
  1729.  
  1730.      26
  1731.  
  1732.  
  1733.  
  1734.                                                      Dialog Box Basics
  1735.  
  1736.      X, Y Coordinates
  1737.  
  1738.      All dialog  box elements require  an X and  Y coordinate.   The Y
  1739.      coordinate  is the  screen row,  while  the X  coordinate is  the
  1740.      screen column.   The dialog box window uses  these coordinates to
  1741.      position the dialog  box as an offset to  the physical upper-left
  1742.      corner of the  screen.   All other  dialog box  elements use  the
  1743.      coordinate as offsets to the upper-left corner of the window.
  1744.  
  1745.      Default Values
  1746.  
  1747.      All  dialog   box   elements   which  can   receive   the   input
  1748.      focus (summarized earlier in Figure 2, page 14) can be designated
  1749.      with an initial  default value.  For  example, a text box  may be
  1750.      pre-filled with  text and a  check box may  be either checked  or
  1751.      unchecked.  Except for the text box, where the default value is a
  1752.      text string,   the default is a number.   Specific default values
  1753.      will  be  discussed for  each  dialog  box  element in  the  next
  1754.      section.
  1755.  
  1756.      Understanding the Elements
  1757.  
  1758.      The section of  the manual  is where each  dialog box element  is
  1759.      fully explained.  It is particularly important since a dialog box
  1760.      template is constructed by gathering  needed DBE definitions into
  1761.      a single include file.
  1762.  
  1763.      We  have  arranged  the  following  pages  so  that the  template
  1764.      structure for  each dialog box element is in  a large box with an
  1765.      explanatory  discussion  immediately  following.     Also,  we've
  1766.      summarized how  each DBE  is initialized  and how  information is
  1767.      returned.
  1768.  
  1769.      You  should know  that  null or  zero  assignments are  perfectly
  1770.      acceptable for many of the array assignments.  For example,  when
  1771.      creating  a  dialog  box  window  you may  optionally  specify  a
  1772.      centered  title in DB().Text.  If you  do not wish to use a title
  1773.      you may assign it to null, like this:
  1774.  
  1775.        DB().Text = ""
  1776.  
  1777.  
  1778.  
  1779.                                                                     27
  1780.  
  1781.  
  1782.  
  1783.  
  1784.      DiaLogic
  1785.  
  1786.      As mentioned earlier, every template definition exists in generic
  1787.      form in  a file  called TEMPLATE.DOC.   You  may simply  transfer
  1788.      portions of this file to your own include file.
  1789.  
  1790.      For your convenience we have summarized the DBE definitions which
  1791.      follow in  a handy  reference section in  Appendix A:  Dialog Box
  1792.      Elements.
  1793.  
  1794.      The Window
  1795.  
  1796.      PURPOSE
  1797.  
  1798.      The  window is responsible  for saving the  underlying screen and
  1799.      creating a background and  frame for a dialog box.   A dialog box
  1800.      template has one and only one window defined.
  1801.  
  1802.      Initial Information:   None
  1803.      Returned Information:  None
  1804.  
  1805.      DB(Level, 1).Code = 1
  1806.        Code for window.
  1807.      DB(Level, 1).Y = 
  1808.        Y coordinate of upper-left corner.
  1809.      DB(Level, 1).X =
  1810.        X coordinate of upper-left corner.
  1811.      DB(Level, 1).Height =
  1812.        Height of window.
  1813.      DB(Level, 1).Wdth =
  1814.        Width of window.
  1815.      DB(Level, 1).BorderType =
  1816.        Border type.  If negative then window will  ``explode.''
  1817.      DB(Level, 1).PrimaryColor =
  1818.        Color of window border. If negative then the window will cast a
  1819.        shadow.
  1820.      DB(Level, 1).WindowColor =
  1821.        Color of  window.  If negative  then a horizontal line  will be
  1822.        drawn near the bottom of the dialog box.
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.      28
  1829.  
  1830.  
  1831.  
  1832.  
  1833.                                                      Dialog Box Basics
  1834.  
  1835.      DB(Level, 1).Text =
  1836.        Optional centered title of the window.
  1837.      DB(Level, 1).TextColor =
  1838.        Color of window title.
  1839.      DB(Level, 1).SecondaryColor =
  1840.        Color of optional bottom horizonal line.
  1841.      DB(Level, 1).NumberOne =
  1842.        Number of screen  lines.  This number may be  25, 43, 50 or 60,
  1843.        depending on the type of display adapter used.  Default is 25.
  1844.  
  1845.      DISCUSSION
  1846.  
  1847.      The window is always the first DBE in a template.  The upper-left
  1848.      corner  of the  window is designated  by DB().X  and DB().Y.   If
  1849.      either coordinate is zero than the window will be centered  along
  1850.      the affected axis.  Thus, to center the dialog box on  the screen
  1851.      both DB().X and DB().Y should be set  to 0.  If positive integers
  1852.      are  used instead then the window  coordinate will be interpreted
  1853.      as a positive offset from the upper-left corner of the screen.
  1854.  
  1855.      The height and  width of the window are  specified by DB().Height
  1856.      and DB().Wdth, respectively.  These dimensions are measured terms
  1857.      of the number of screen characters down and across.
  1858.  
  1859.      The color of the window border is specified by DB().PrimaryColor;
  1860.      the  color of the window is in DB().WindowColor; the color of the
  1861.      bottom  horizontal  line   (discussed  below)  is   contained  in
  1862.      DB().SecondaryColor.   A centered  window title may  be placed in
  1863.      DB().Text.    The  color  of  the  window  title  is  defined  by
  1864.      DB().TextColor.
  1865.  
  1866.      Some of the  assignments we've mentioned  so far have  additional
  1867.      potential.   For example, if DB().BorderType is negative then the
  1868.      window will  ``explode''  when  drawn;  if  DB().PrimaryColor  is
  1869.      negative then the window will appear to cast  a shadow; and last,
  1870.      if  DB().WindowColor is  negative  then the  window  will have  a
  1871.      bottom  horizontal line.  (This horizontal line usually serves as
  1872.      a divider between the upper contents of the window and a lower 
  1873.  
  1874.  
  1875.  
  1876.  
  1877.                                                                     29
  1878.  
  1879.  
  1880.  
  1881.  
  1882.      DiaLogic
  1883.  
  1884.      line of command  buttons.)  Although the numbers  may be negative
  1885.      you should realize that this serves as a  flag only: the absolute
  1886.      values are always  used.  The window  is the only DBE  that makes
  1887.      use of negative-value flags in its template definition.
  1888.  
  1889.      Finally,  DB().NumberOne  holds   the  number  of   screen  lines
  1890.      currently being used,  and may be set  to values such as  25, 43,
  1891.      50, or 60.   If DB().NumberOne is 0  then the default is  25.  If
  1892.      the window's Y coordinate  is 0 then  this value is  particularly
  1893.      important: it is used in calculations for centering a dialog  box
  1894.      along its vertical axis.
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.      30
  1927.  
  1928.  
  1929.  
  1930.  
  1931.                                                      Dialog Box Basics
  1932.  
  1933.      Text Box
  1934.  
  1935.      PURPOSE
  1936.  
  1937.      The text box allows  the user to  type text information  directly
  1938.      from the keyboard.
  1939.  
  1940.      Initial Information:   DB().TextString
  1941.      Returned Information:  DB().TextString, DB().NumberOne
  1942.  
  1943.      DB().Code = 2
  1944.        Code for text box.
  1945.      DB().Y = 
  1946.        Y coordinate of upper-left corner.
  1947.      DB().X =
  1948.        X coordinate of upper-left corner.
  1949.      DB().Wdth =
  1950.        Width of text box.
  1951.      DB().BorderType =
  1952.        Border type.
  1953.      DB().PrimaryColor =
  1954.        Border color.
  1955.      DB().WindowColor =
  1956.        Color of unselected text inside the text box window.
  1957.      DB().SelectedColor =
  1958.        Color of selected text.
  1959.      DB().TextY =
  1960.        Y coordinate for text box label.
  1961.      DB().TextX =
  1962.        X coordinate for text box label.
  1963.      DB().Text =
  1964.        Text box label.  May contain a tilde for Alt-key operation.
  1965.      DB().TextColor =
  1966.        Color of text box label.
  1967.      DB().KeyColor =
  1968.        Color of the Alt-key in the text box label.
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.                                                                     31
  1976.  
  1977.  
  1978.  
  1979.  
  1980.      DiaLogic
  1981.  
  1982.      DB().TextString =
  1983.        Text box default edit string.
  1984.      DB().ItemLength =
  1985.        Maximum number of characters which may be entered.
  1986.      DB().NumberOne =
  1987.        Length of the returned string (held by DB().TextString).
  1988.  
  1989.      DISCUSSION
  1990.  
  1991.      The  location, width, border type, and border color are specified
  1992.      in the same manner as for the window.
  1993.  
  1994.      Text in a text box  may be highlighted (or selected) by  dragging
  1995.      the  mouse  while a  mouse  button is  pressed,  or by  using the
  1996.      <Shift> key in combination  with the directional keys.   Selected
  1997.      text is usually marked for deletion on the next key press.  Since
  1998.      unselected text and  selected text  should be distinguishable  to
  1999.      the user,  two different attributes  are usually  used for  each:
  2000.      DB().WindowColor   is   the   attribute  for   unselected   text;
  2001.      DB().SelectedColor is the attribute for selected text.
  2002.  
  2003.      Text boxes  may be  labelled with  text, such  as ``File  Name''.
  2004.      Such text is specified  by DB().Text; the  location of this  text
  2005.      (usually  placed to the  left of  the text  box) is  indicated by
  2006.      DB().TextY  and  DB().TextX;  the  color   of  the  label  is  in
  2007.      DB().TextColor.  Further, the text box label may have an embedded
  2008.      Alt-key.   For  example,  the ``File Name''  label  could have  a
  2009.      highlighted ``F''  to indicate  that an Alt-key  is present.   In
  2010.      this instance, you would make an assignment like this:
  2011.  
  2012.        DB().Text = "~File Name"
  2013.  
  2014.      The color of the Alt-key is specified by DB().KeyColor.
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.      32
  2025.  
  2026.  
  2027.  
  2028.  
  2029.                                                      Dialog Box Basics
  2030.  
  2031.      The text  box uses DB().TextString to  hold the edit string.   If
  2032.      DB().TextString   is  initialized  before   the  dialog   box  is
  2033.      displayed, then the text  box will be  filled with the  specified
  2034.      string.    Any   changes  to  this  string  will   be  stored  in
  2035.      DB().TextString.  For  example, suppose that  we wish to  present
  2036.      the  user with  the  current disk  drive.   We  could place  this
  2037.      information into  a variable  called DefaultDrive$,  then in  our
  2038.      template definition we could make an assignment similar to:
  2039.  
  2040.        DB().TextString = DefaultDrive$
  2041.  
  2042.      When  DiaLogic  returns  information   you  should  realize  that
  2043.      DB().TextString is a fixed-length string  and that the string  it
  2044.      contains will  be padded with right-side spaces.   If you wish to
  2045.      ignore these  spaces you  may use BASIC's  RTRIM$ function.   For
  2046.      example:
  2047.  
  2048.        TrimmedString$ = RTRIM$(DB(1, 3).TextString)
  2049.  
  2050.      This statement removes the right-side  spaces in the fixed-length
  2051.      string held  in DB(1, 3).TextString,  and copies the  result into
  2052.      the conventional (variable-length)  string called TrimmedString$.
  2053.      But   RTRIM$   removes   all   right-side   spaces,  even   those
  2054.      intentionally entered by the user.  For this  reason we have used
  2055.      DB().NumberOne to  hold the  true length of  the text  box string
  2056.      that  was entered  by  the user.    Thus, you  may  ascertain the
  2057.      correct edit string by using the following statement:
  2058.  
  2059.        EditString$ = MID$(DB().TextString, 1, DB().NumberOne)
  2060.  
  2061.      The  maximum length of  the text box  string may be  specified in
  2062.      DB().ItemLength.  The  text box will  cease to accept  characters
  2063.      beyond the length specified.
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.                                                                     33
  2074.  
  2075.  
  2076.  
  2077.  
  2078.      DiaLogic
  2079.  
  2080.      List Box
  2081.  
  2082.      PURPOSE
  2083.  
  2084.      The list box presents the user with a list of items through which
  2085.      to scroll and ultimately from which to make a selection.
  2086.  
  2087.      Initial Information:   DB().Default 
  2088.      Returned Information: DB().Default
  2089.  
  2090.      DB().Code = 3
  2091.        Code for list box.DB().Y = 
  2092.        Y coordinate of upper-left corner.
  2093.      DB().X =
  2094.        X coordinate of upper-left corner.
  2095.      DB().Height =
  2096.        No. items vertically within the list box borders.
  2097.      DB().Wdth =
  2098.        No. items horizontally within the list box borders.
  2099.      DB().WindowColor = 
  2100.        Color of ``empty'' space within list box borders.
  2101.      DB().PrimaryColor =
  2102.        Color of primary list box items.
  2103.      DB().SecondaryColor =
  2104.        Color of secondary list box items.
  2105.      DB().SelectedColor =
  2106.        Color of selected items.
  2107.      DB().StarColor =
  2108.        Color of scroll bars.
  2109.      DB().ItemLength =
  2110.        Length of a single list box item.
  2111.      DB().KeyColor = 
  2112.        Number of spaces between list box columns.
  2113.      DB().BorderType =
  2114.        Scroll bars: 0=none; 1=bottom; 2=side; 3=both.
  2115.      DB().Link =
  2116.        Link code. 0=none; >0=text-box; <0=sentence.
  2117.      DB().TextY =
  2118.        Y coordinate for sentence links.
  2119.      DB().TextX =
  2120.        X coordinate for sentence links.
  2121.  
  2122.  
  2123.  
  2124.      34
  2125.  
  2126.  
  2127.  
  2128.  
  2129.                                                      Dialog Box Basics
  2130.  
  2131.      DB().TextColor =
  2132.        Color of sentence links.
  2133.      DB().NumberOne =
  2134.        LB() starting element.
  2135.      DB().NumberTwo =
  2136.        LB() ending element.
  2137.      DB().Default   =
  2138.        The LB() array element number to be selected by default.
  2139.  
  2140.  
  2141.      DISCUSSION
  2142.  
  2143.      The list box is extremely  powerful due to its sheer flexibility.
  2144.      The upper-left corner of the list box  is specified by DB().X and
  2145.      DB().Y.  The height and  width are  specified by  DB().Height and
  2146.      DB().Wdth in terms of the number of items to be listed vertically
  2147.      and horizontally.   The length of each list box item is specified
  2148.      by DB().ItemLength; the number of spaces between list box columns
  2149.      is specified  by DB().KeyColor.   Thus, the  width of a  list box
  2150.      will  equal the number of items  across (DB().Wdth) multiplied by
  2151.      the      itemlength      plus     space      between      columns
  2152.      (DB().ItemLength + DB().KeyColor).
  2153.  
  2154.      DB().WindowColor specifies the color of  the list box window.  In
  2155.      this assignment  the foreground is  used as the border  color and
  2156.      the background color will serve  both the border and window area.
  2157.      The list box border is always a single line.
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.                                                                     35
  2175.  
  2176.  
  2177.  
  2178.  
  2179.      DiaLogic
  2180.  
  2181.      An item  in a  list  box may  be printed  in one  of two  colors,
  2182.      depending on the presence of a leading tilde.  The first color is
  2183.      specified  by   DB().PrimaryColor  while  the  second   color  is
  2184.      specified by DB().SecondaryColor.  Any list box item which has  a
  2185.      tilde as its  first character is printed in  the secondary color;
  2186.      all other items are displayed in the primary color.  For example,
  2187.      if we were to create a list  box to display available directories
  2188.      and files, we may choose to display the directory  names in blue-
  2189.      on-white (color 113) and the file names in  black-on-white (color
  2190.      112):
  2191.  
  2192.        LB(1).Text = "~DOS"
  2193.        LB(2).Text = "~QB"
  2194.        LB(3).Text = "~WP50"
  2195.        LB(4).Text = "COMMAND.COM"
  2196.        LB(5).Text = "AUTOEXEC.BAT"
  2197.        LB(6).Text = "CONFIG.SYS"
  2198.           .
  2199.           .
  2200.           .
  2201.  
  2202.      The above LB() items show how such assignments actually are made.
  2203.      The first 3  elements represent directory names while  the last 3
  2204.      represent file names.  In  order for these items to be  displayed
  2205.      in the colors we specified, the list box template definition must
  2206.      have assignments similar to the following:
  2207.  
  2208.        DB(1, 3).PrimaryColor = 112
  2209.        DB(1, 3).SecondaryColor = 113
  2210.  
  2211.      Only one  item  in  a list  box  is  selected at  a  time.    The
  2212.      currently-selected item is displayed using the color specified by
  2213.      DB().SelectedColor.   Please be aware that, depending on the type
  2214.      of list box, there may be no selected item until the user makes a
  2215.      choice.  If you do not want an item to be selected (such as for a
  2216.      help list box) then use -1 for DB().SelectedColor.
  2217.  
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.      36
  2224.  
  2225.  
  2226.  
  2227.  
  2228.                                                      Dialog Box Basics
  2229.  
  2230.      Scroll  bars are  optional  for  list boxes.    At  least one  is
  2231.      recommended since it will provide a means of discerning how  much
  2232.      information is  contained  by the  list  box.   Wide  list  boxes
  2233.      usually have  a single  bottom scroll bar;  narrow but  tall list
  2234.      boxes make better use of a right-side scroll bar.  It most always
  2235.      is superfluous to display both scroll bars.
  2236.  
  2237.      The presence of  a scroll bar is indicated  by DB().BorderType as
  2238.      follows:
  2239.  
  2240.  
  2241.  
  2242.        DB().BorderType   Resulting Scroll Bar(s)
  2243.  
  2244.             0            No scroll bars
  2245.             1            A bottom scroll bar
  2246.             2            A right scroll bar
  2247.             3            Both bottom and right scroll bars
  2248.  
  2249.  
  2250.      The color of a scroll bar is indicated by DB().StarColor.
  2251.  
  2252.      One of the  most powerful features of DiaLogic is  the ability to
  2253.      link a list box item.  Linking  takes two forms: text-box linking
  2254.      and  sentence  linking.    Text-box  links allow  the  currently-
  2255.      selected list box item to be placed automatically in a text  box.
  2256.      Sentence links allow a list box item to be printed in  a context-
  2257.      sensitive description anywhere  on the dialog  box.  Examples  of
  2258.      both link  types  are shown  in the  DEMO  and explained  further
  2259.      below.
  2260.  
  2261.      The type of  link you wish to  use is indicated by DB().Link.   A
  2262.      certain list box may  make use of only  one link type at  a time,
  2263.      however, list boxes in a dialog box may be using different links.
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.                                                                     37
  2273.  
  2274.  
  2275.  
  2276.  
  2277.      DiaLogic
  2278.  
  2279.      A text-box link is created when  DB().Link is greater than 0.  In
  2280.      this instance DB().Link  must equal a Sequence number  for a text
  2281.      box in your template.
  2282.  
  2283.  
  2284.        Note:
  2285.           A Sequence number  is the second  subscript in  the DB()
  2286.           array.  Thus, it  is unique for each dialog box  element
  2287.           in a dialog box.  The importance of Sequence  numbers is
  2288.           discussed further in the tutorial section.
  2289.  
  2290.  
  2291.      Sentence links  are a little more complex, and are specified when
  2292.      DB().Link is less  than 0.  A  sentence link should be  used when
  2293.      you wish to  describe list box items  to the user.   For example,
  2294.      suppose we use the Directory/File list box mentioned earlier.  We
  2295.      may want a description  to appear below the  list box which  will
  2296.      tell the user if the current item is a directory or  a file, and,
  2297.      if is a  file, we may  want to indicate  which files are  hidden.
  2298.      Let's assume the following:  if the selected item is a directory,
  2299.      we'll print the message:
  2300.  
  2301.        DIRECTORYNAME is a directory.
  2302.  
  2303.      And for files, we'll use one sentence if it is a regular file and
  2304.      another type of sentence if it is a hidden file:
  2305.  
  2306.        FILENAME is a File.
  2307.  
  2308.      and
  2309.  
  2310.        The file FILENAME is hidden.
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.      38
  2322.  
  2323.  
  2324.  
  2325.  
  2326.                                                      Dialog Box Basics
  2327.  
  2328.      In each  sentence above,  the italicized  name is  the item  name
  2329.      taken directly from the list box.  The rest of the sentence, like
  2330.      the list box item itself, is defined in the LB() array.
  2331.  
  2332.      If sentence links are  used then the  appropriate portion of  the
  2333.      LB() array must be filled using the following syntax:
  2334.  
  2335.        LB().Text="[PRESTRING],[~]ITEMSTRING,[POSTSTRING]"
  2336.  
  2337.      Notice that  the optional  tilde appears in  front of  the second
  2338.      string.  
  2339.      The  above  syntax   describes  each  LB()  array   string  as  a
  2340.      concatenation  of  three strings:  a  prestring, itemstring,  and
  2341.      poststring.  Please note  that  this  syntax  is used  only  when
  2342.      DB().Link  is less than zero.  The itemstring is what will appear
  2343.      in the list box and also optionally in the sentence link.
  2344.  
  2345.      Once  LB()  has  been  properly  assigned,  you  may construct  a
  2346.      sentence  link  using  various  combinations  of  the  prestring,
  2347.      itemstring, and poststring  components.  All sentence links use a
  2348.      DB().Link value less than 0.
  2349.  
  2350.      For example, if  DB().Link were -1, and the selected  item in the
  2351.      list box had a corresponding LB() array string like this:
  2352.  
  2353.        LB(5).Text = ",DIALOGIC.QLB, is a Quick Library"
  2354.  
  2355.      then whenever the list box item ``DIALOGIC.QLB'' is selected this
  2356.      sentence will appear:
  2357.  
  2358.        DIALOGIC.QLB is a Quick Library
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.                                                                     39
  2371.  
  2372.  
  2373.  
  2374.  
  2375.      DiaLogic
  2376.  
  2377.      In  this  example  the  prestring  is  null;  the  itemstring  is
  2378.      ``DIALOGIC.QLB'', and the poststring is `` is a Quick Library''.
  2379.      All list box link codes are summarized below.  You  should review
  2380.      the DEMO  to observe  how sentence links  and text-box  links are
  2381.      used by list boxes.
  2382.  
  2383.  
  2384.        DB().Link   Description
  2385.  
  2386.         >0         Any link code greater than zero will be  a text-box
  2387.                    link and will  attempt to  link to the  DBE in  the
  2388.                    template  with the Sequence  number specified.  For
  2389.                    example, if DB().Link is 5,  then the fifth element
  2390.                    in the template must be a text box.
  2391.          0         No link will take place
  2392.         -1         The  prestring,  itemstring,  and   poststring  are
  2393.                    displayed together
  2394.         -2         Only the prestring is displayed
  2395.         -3         Only the itemstring is displayed
  2396.         -4         Only the poststring is displayed
  2397.  
  2398.  
  2399.  
  2400.      The sentence which results is displayed by  the attribute defined
  2401.      by DB().TextColor;  the location of the sentence  is specified by
  2402.      DB().TextX and DB().TextY.
  2403.  
  2404.      Since  all  list  boxes  access  the  LB()  array  we  have  used
  2405.      DB().NumberOne and  DB().NumberTwo  to specify  the starting  and
  2406.      ending elements, respectively.   For example, the LB()  array may
  2407.      contain 100 elements.  However, there may  be 2 list boxes on the
  2408.      current  dialog box.  In  this instance, one  list box may access
  2409.      LB() array  elements 1  through 60,  while the  other may  access
  2410.      elements 61 through 100.   This method allows certain list  boxes
  2411.      to access a very specific part of the entire LB() array.
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.      40
  2420.  
  2421.  
  2422.  
  2423.  
  2424.                                                      Dialog Box Basics
  2425.  
  2426.      If a list box is empty you will want to assign DB().NumberOne and
  2427.      DB().NumberTwo to zero.  This will cause the  input focus to skip
  2428.      the empty list box.
  2429.  
  2430.      Finally, DB().Default allows a  list box item  to be selected  by
  2431.      default.  The number in DB().Default is the element number of the
  2432.      LB()  array  and   must  fall  within  the   range  specified  by
  2433.      DB().NumberOne and DB().NumberTwo.  If the user makes a selection
  2434.      from the list box  then DB().Default will  be updated and may  be
  2435.      inspected by  the calling  program.   If  no  list box  item  was
  2436.      selected then DB().Default will be 0.
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.                                                                     41
  2469.  
  2470.  
  2471.  
  2472.  
  2473.      DiaLogic
  2474.  
  2475.      Check Box
  2476.  
  2477.      PURPOSE
  2478.  
  2479.      The check box provides  a simple way to turn an  option ``on'' or
  2480.      ``off''.
  2481.  
  2482.      Initial Information:   DB().Default
  2483.      Returned Information:  DB().Default
  2484.  
  2485.      DB().Code = 4
  2486.        Code for check box.
  2487.      DB().Y =
  2488.        Y coordinate of check box's left bracket.
  2489.      DB().X =
  2490.        X coordinate of check box's left bracket.
  2491.      DB().PrimaryColor =
  2492.        Color when unselected.
  2493.      DB().SelectedColor =
  2494.        Color when selected.
  2495.      DB().TextY =
  2496.        Y coordinate for check box label.
  2497.      DB().TextX =
  2498.        X coordinate for check box label.
  2499.      DB().Text =
  2500.        Check box label.  May contain a tilde for Alt-key function.
  2501.      DB().TextColor =
  2502.        Color of check box label.
  2503.      DB().KeyColor =
  2504.        Color of the alt-key in the check box label.
  2505.      DB().StarColor =
  2506.        Toggle star color.
  2507.      DB().Default =
  2508.        Default status of check box. 0=off; -1=on.
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.      42
  2518.  
  2519.  
  2520.  
  2521.  
  2522.                                                      Dialog Box Basics
  2523.  
  2524.      DISCUSSION
  2525.  
  2526.      Check boxes are placed  anywhere on the  screen using DB().X  and
  2527.      DB().Y.   When a check box is selected  (using the arrow keys, an
  2528.      Alt-key, or the  mouse) a capital X  will appear inside  it; when
  2529.      unselected, a space will appear:
  2530.  
  2531.        [X]      Selected check box
  2532.        [ ]      Unselected check box
  2533.  
  2534.      The color of  the space is  indicated by DB().SecondaryColor  and
  2535.      the color of the X is indicated by DB().SelectedColor.
  2536.  
  2537.      Check boxes may  have a label  associated with them  in the  same
  2538.      sense that text boxes have a label.  The location of the label is
  2539.      specified by DB().TextX  and DB().TextY; label text  is specified
  2540.      by DB().Text; label color is specified by DB().TextColor.  If  an
  2541.      Alt-key is desired the tilde character must  be used in the label
  2542.      text.  The color of the Alt-key is indicated by DB().KeyColor.
  2543.  
  2544.      If the  mouse is  being used  then a selection  toggle star  will
  2545.      appear  as the mouse  is dragged across  a check box.   This star
  2546.      marks the active check  box.  The color of the  star is specified
  2547.      by DB().StarColor.
  2548.  
  2549.      Finally, the default value  and returned information are  held in
  2550.      DB().Default.  If  the default value is  0 then the check  box is
  2551.      unselected; if -1 then the check box is selected.
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.                                                                     43
  2567.  
  2568.  
  2569.  
  2570.  
  2571.      DiaLogic
  2572.  
  2573.      Option Buttons
  2574.  
  2575.      PURPOSE
  2576.  
  2577.      Option buttons are  useful when a single option  must be selected
  2578.      among several choices.
  2579.  
  2580.      Initial Information:   DB().Default
  2581.      Returned Information:  DB().Default
  2582.  
  2583.      DB().Code = 5
  2584.        Code for option buttons.
  2585.      DB().NumberOne =
  2586.        Number of option buttons in this cluster.
  2587.      DB().Default =
  2588.        Default option button.
  2589.      DB().TextString =
  2590.        Location string  holding coordinates  for  each button  in  the
  2591.        cluster.
  2592.      DB().WindowColor =
  2593.        Color of button's parentheses.
  2594.      DB().SelectedColor =
  2595.        Color (of centered dot) when selected.
  2596.      DB().StarColor =
  2597.        Color of toggle star.
  2598.  
  2599.  
  2600.  
  2601.  
  2602.  
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.      44
  2616.  
  2617.  
  2618.  
  2619.  
  2620.                                                      Dialog Box Basics
  2621.  
  2622.      DISCUSSION
  2623.  
  2624.      Option buttons are defined  in clusters.   The maximum number  of
  2625.      buttons in  a cluster  is 10.   The exact  number in  the cluster
  2626.      being defined  is specified by DB().NumberOne.   For example, the
  2627.      cluster below represents a  single cluster comprised of 3  option
  2628.      buttons:
  2629.  
  2630.        ( )
  2631.        ( )
  2632.        (.)
  2633.  
  2634.      Because  each button in  a cluster may be  placed anywhere in the
  2635.      dialog box, we  have not made  use of a  solitary X-Y  coordinate
  2636.      pair.    Instead, we  have  allowed  all  the coordinates  to  be
  2637.      specified  in  a  string  contained  in  DB().TextString.    Each
  2638.      coordinate is delimited from the next  by a comma and, like other
  2639.      DBEs, each coordinate is an offset from the upper-left corner  of
  2640.      the dialog  box window.   For example, if we  wanted three option
  2641.      buttons at  column 10  and rows  5, 6  and 7,  then the  location
  2642.      string would be:
  2643.  
  2644.        DBE().TextString = "5,10,6,10,7,10"
  2645.  
  2646.      This string is parsed  by DiaLogic: it  is neither necessary  nor
  2647.      desirable to have any embedded spaces.
  2648.  
  2649.      The color of the option button border (that is, its  parentheses)
  2650.      is specified by  DB().WindowColor.  The color of  the button when
  2651.      selected (that is, the color of the centered dot) is specified by
  2652.      DB().SelectedColor.  As with the  check box, option buttons  also
  2653.      have a  toggle star.   The  color of  the star  is designated  by
  2654.      DB().StarColor.
  2655.  
  2656.  
  2657.  
  2658.  
  2659.  
  2660.  
  2661.  
  2662.  
  2663.  
  2664.                                                                     45
  2665.  
  2666.  
  2667.  
  2668.  
  2669.      DiaLogic
  2670.  
  2671.      The button which is to be selected at the start and the one which
  2672.      was selected by the user is held  in DB().Default.  The number it
  2673.      contains  corresponds sequentially  to the  buttons specified  in
  2674.      DB().TextString.  Thus, in  our example, button one is  at 5, 10;
  2675.      button two is  at 6, 10;  and button three  is at 7,  10.  If  we
  2676.      wanted the  second button  to be  selected at  the start  then we
  2677.      would assign DB().Default to 2.
  2678.  
  2679.      You may notice that there are no assignments for labelling option
  2680.      buttons.  This is  because all option  buttons are labelled  with
  2681.      smart labels.
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.      46
  2714.  
  2715.  
  2716.  
  2717.  
  2718.                                                      Dialog Box Basics
  2719.  
  2720.      Smart Labels
  2721.  
  2722.      PURPOSE
  2723.  
  2724.      Smart labels may  be used to place  text anywhere on  the screen.
  2725.      But the power offered by smart  labels is the ability to form  an
  2726.      Alt-key link  to any  dialog box  element which  can receive  the
  2727.      input  focus.   This  ability makes  them particularly  ideal for
  2728.      labelling option buttons.
  2729.  
  2730.      Initial Information:   None
  2731.      Returned Information:  None
  2732.  
  2733.      DB().Code = 6
  2734.        Code for smart label.
  2735.      DB().Y =
  2736.        Y coordinate of smart label text.
  2737.      DB().X =
  2738.        X coordinate of smart label text.
  2739.      DB().Text =
  2740.        Smart label text.  May contain a tilde for alt-key function.
  2741.      DB().TextColor =
  2742.        Color of smart label.
  2743.      DB().KeyColor =
  2744.        Color of the alt-key in the smart label text.
  2745.      DB().Link =
  2746.        Sequence of the  dialog box element  which is to be  an Alt-key
  2747.        link to this smart label.
  2748.      DB().NumberOne =
  2749.        Button number for a linked option button cluster.
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.                                                                     47
  2763.  
  2764.  
  2765.  
  2766.  
  2767.      DiaLogic
  2768.  
  2769.      DISCUSSION
  2770.  
  2771.      Smart labels are placed on the screen at a location  specified by
  2772.      DB().X and DB().Y.   The label text is defined  by DB().Text; the
  2773.      label color is specified by DB().TextColor.  This information  is
  2774.      all that is needed if you wish simply to create a label.
  2775.  
  2776.      However, if you wish to create an  Alt-key link then you must not
  2777.      only define the Alt-key but also the dialog box element to  which
  2778.      the Alt-key will  be linked.  The Alt-key  character is specified
  2779.      when a tilde precedes it in DB().Text.   The Alt-key link is held
  2780.      in DB().Link and  corresponds to the dialog  box element Sequence
  2781.      number.
  2782.  
  2783.      For example, if  you wish to label  a list box with text  such as
  2784.      ``Available Files,''  you may  wish to create  an Alt-key  so the
  2785.      keyboard user  can jump  directly to  this list  box without  the
  2786.      repeated use of the <Tab> key or use of the mouse.  If you decide
  2787.      to make the  first ``A'' the Alt-key, then  your label assignment
  2788.      would look something like this:
  2789.  
  2790.        DB().Text = "~Available Files"
  2791.  
  2792.      If the list box you wish to  link to is the third in the Sequence
  2793.      of  dialog  box  elements  in  the  template,  you  would  assign
  2794.      DB().Link as follows:
  2795.  
  2796.        DB().Link = 3
  2797.  
  2798.      In  our example, if the user  presses <Alt>A then the input focus
  2799.      will be transferred to the list box.
  2800.  
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.      48
  2812.  
  2813.  
  2814.  
  2815.  
  2816.                                                      Dialog Box Basics
  2817.  
  2818.      If the smart label is used  for option buttons then an additional
  2819.      assignment  must  be made.    DB().Link  will  still be  used  to
  2820.      indicate the Sequence number  of the option  button cluster.   In
  2821.      addition, DB().NumberOne indicates to which button in the cluster
  2822.      the smart label is to be linked.  If DB().NumberOne is 2 then the
  2823.      second option button in  the cluster indicated by DB().Link  will
  2824.      be accessed when the Alt-key is pressed.
  2825.  
  2826.      All smart labels are mouse-sensitive.  If the mouse is clicked on
  2827.      a smart label and  a link is defined then the input focus will be
  2828.      transferred as expected.
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.  
  2849.  
  2850.  
  2851.  
  2852.  
  2853.  
  2854.  
  2855.  
  2856.  
  2857.  
  2858.  
  2859.  
  2860.                                                                     49
  2861.  
  2862.  
  2863.  
  2864.  
  2865.      DiaLogic
  2866.  
  2867.      Command Buttons
  2868.  
  2869.      PURPOSE
  2870.  
  2871.      Command buttons cause control  to be passed  back to the  calling
  2872.      program so  that some  action may  be carried  out.   This action
  2873.      usually  removes  the  dialog  box  but  sometimes  may  open  an
  2874.      overlaying one.  Typical  command buttons are <OK>  and <Cancel>.
  2875.      All command  buttons  return  a  unique keystroke  value  to  the
  2876.      calling program.
  2877.  
  2878.      Initial Information:   DB().Default
  2879.      Returned Information:  DB().Default, Ky$
  2880.  
  2881.      DB().Code = 7
  2882.        Code for command button.
  2883.      DB().Y =
  2884.        Y coordinate of upper-left corner.
  2885.      DB().X =
  2886.        X coordinate of upper-left corner.
  2887.      DB().Text =
  2888.        Command button text.  May contain a tilde for Alt-key function.
  2889.      DB().PrimaryColor = 
  2890.        Color of angle brackets when command button is inactive.
  2891.      DB().SecondaryOne =
  2892.        Color of angle brackets when command button is active.
  2893.      DB().WindowColor =
  2894.        Color of text between angle brackets when unselected.
  2895.      DB().SelectedColor =
  2896.        Color of command button when selected.
  2897.      DB().KeyColor =
  2898.        Color of the Alt-key character.
  2899.      DB().Default =
  2900.        Default status: -1=on; 0=off.
  2901.      DB().TextString =
  2902.        Sets Ky$ return value for this command button.   This should be
  2903.        a valid key string, such as CHR$(27) for <Esc>.
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.      50
  2910.  
  2911.  
  2912.  
  2913.  
  2914.                                                      Dialog Box Basics
  2915.  
  2916.      DISCUSSION
  2917.  
  2918.      A command  button always returns  control to the  calling program
  2919.      and, in this respect,  it is said to close  a dialog box.   Every
  2920.      dialog box  will have  a single  active command  button which  is
  2921.      distinguished by a pair of highlighted angle brackets.  A command
  2922.      button  is  ``pushed''  in  several  ways,  but  you  must  first
  2923.      understand that a  single default command  button is defined  for
  2924.      every dialog  box.   This default  is active  whenever the  input
  2925.      focus is on a dialog box element other than a command button.  An
  2926.      active command button has its angle brackets highlighted. 
  2927.  
  2928.      For  example, let's  assume that  <OK>  has been  defined as  the
  2929.      default for  a dialog  box which has  two other  command buttons:
  2930.      <Cancel> and <Help>.   Also, assume that  there is a text  box in
  2931.      this dialog box.  When  the input focus is on the  text box, <OK>
  2932.      will be active because it is the  default command button.  But if
  2933.      the  input focus  is  transferred to  <Help>,  for example,  then
  2934.      <Help> will be active  and <OK> will  no longer have  highlighted
  2935.      angle brackets.
  2936.  
  2937.      Command buttons may be pushed in a variety of ways:
  2938.  
  2939.         *  By using a command button Alt-key
  2940.         *  By pressing <Enter>  when the  desired command  button is
  2941.            active
  2942.         *  By pressing a command-button key
  2943.         *  By clicking on a command button using the mouse
  2944.  
  2945.      All active command buttons return information in Ky$ so that  the
  2946.      calling program may react accordingly.  The information in Ky$ is
  2947.      the command-button key.
  2948.  
  2949.      Command  buttons are  placed in  a  dialog box  using DB().X  and
  2950.      DB().Y.    The  text  in  the  command  button  is  specified  by
  2951.      DB().Text, which  may contain an Alt-key.   The color of the Alt-
  2952.      key is specified by DB().KeyColor.
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.                                                                     51
  2959.  
  2960.  
  2961.  
  2962.  
  2963.      DiaLogic
  2964.  
  2965.      The color of an active command button is held in  DB().NumberOne.
  2966.      The  color of the  command button  when it  is selected  with the
  2967.      mouse is held in DB().SelectedColor.   By convention the selected
  2968.      color is inverse to  the unselected color.  For  instance, if the
  2969.      command button  text is black-on-white, then it  should be white-
  2970.      on-black when selected.   The selected color for command  buttons
  2971.      serves the  same purpose as the toggle star  of the check box and
  2972.      option buttons.
  2973.  
  2974.      The default command button must set DB().Default to -1.  If  none
  2975.      of  the command buttons in a template  has the default flag, then
  2976.      DiaLogic will automatically assign it  to the last command button
  2977.      processed.  There must always be one default  command button in a
  2978.      dialog box.
  2979.  
  2980.      The key  to be  associated with  a particular  command button  is
  2981.      defined in DB().TextString.   This  way, you  may easily  emulate
  2982.      what IBM  has done in  the DOS 4.0  shell:  most  command buttons
  2983.      have associated function keys, and  usually appear something like
  2984.      this:
  2985.  
  2986.        <F1=Help>
  2987.  
  2988.      In this instance you must know that <F1> has a keyboard scan code
  2989.      of  CHR$(0)+CHR$(59).   (If scan codes  are new  to you  they are
  2990.      summarized  in  the  QuickBASIC 4.0  Language  Reference  Manual,
  2991.      pp. 462-463).  DiaLogic will return <F1> as the last keypress  if
  2992.      the above command button had been pushed, and the calling program
  2993.      can react the same way as if the <F1> key was actually pressed by
  2994.      the user.
  2995.  
  2996.      Additionally,  you may  examine  DB().Default command  button  to
  2997.      determine which one was  active when the  dialog box was  closed.
  2998.      If the value  of DB().Default is -1 then that  command button was
  2999.      active.
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.      52
  3008.  
  3009.  
  3010.  
  3011.  
  3012.                                                      Dialog Box Basics
  3013.  
  3014.      Group Box
  3015.  
  3016.      PURPOSE
  3017.  
  3018.      The  group box  places an optionally-labelled  box in  the dialog
  3019.      box.   It  is commonly  used  to visually  enclose related  input
  3020.      regions of the dialog box.
  3021.  
  3022.      Initial Information:   None
  3023.      Returned Information:  None
  3024.  
  3025.      DB().Code = 8
  3026.        Code for group box.
  3027.      DB().Y =
  3028.        Y coordinate of upper-left corner.
  3029.      DB().X =
  3030.        X coordinate of upper-left corner.
  3031.      DB().Height =
  3032.        Height of box.
  3033.      DB().Wdth =
  3034.        Width of box.
  3035.      DB().BorderType =
  3036.        Border type.
  3037.      DB().SecondaryColor =
  3038.        Color of group box border.
  3039.      DB().Text =
  3040.        Text for the top center of group box.
  3041.      DB().TextColor =
  3042.        Color of the text label.
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.  
  3055.  
  3056.                                                                     53
  3057.  
  3058.  
  3059.  
  3060.  
  3061.      DiaLogic
  3062.  
  3063.      DESCRIPTION
  3064.  
  3065.      The upper-left corner of the group box is specified by DB().X and
  3066.      DB().Y.  The dimensions of the box (in characters) are  specified
  3067.      in  DB().Height  and DB().Wdth.    The  type  of border  used  is
  3068.      indicated by DB().BorderType.  The color of the group box  border
  3069.      is indicated by DB().SecondaryColor.
  3070.  
  3071.      The label, if specified, will be centered at the top of the group
  3072.      box.  The label text is specified by DB().Text, and the  color of
  3073.      the label is held in DB().TextColor.
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.      54
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.  
  3114.  
  3115.  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.  
  3121.                                   DiaLogic
  3122.  
  3123.  
  3124.  
  3125.                                   PART III
  3126.                             CREATING A TEMPLATE
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.                                                    Creating a Template
  3134.  
  3135.      Templates specify the exact appearance of a dialog box.  Appendix
  3136.      A: The Dialog  Box Elements In  Detail will prove  to be a  handy
  3137.      source  of  reference  when  creating  templates.    It  contains
  3138.      extensive information about each dialog box element and should be
  3139.      reviewed frequently.  
  3140.  
  3141.  
  3142.      Summary
  3143.  
  3144.  
  3145.      (1)  Making a sketch
  3146.      (2)  Determining the Sequence
  3147.      (3)  Copying & pasting
  3148.      (4)  Making the assignments
  3149.  
  3150.      Creating  a template  consists  of the  four  steps shown  above.
  3151.      First, you should decide how your dialog  box is to appear to the
  3152.      user.  Second, you should determine a Sequence for its  elements.
  3153.      Third, you  should copy  & paste the  relevant portions  from the
  3154.      generic template  to your  own template  file.   And fourth,  you
  3155.      should complete  the array assignments  in the new  template with
  3156.      values which will yield the desired dialog box.
  3157.  
  3158.  
  3159.      A Detailed Example
  3160.  
  3161.      We  will  present  in  this  section  an  excruciatingly-detailed
  3162.      account of creating a dialog box template using the steps  above.
  3163.      Please bear with  us!  The first  time through may seem  tedious,
  3164.      but the process will grow comfortable over time.
  3165.  
  3166.      We will construct a  dialog box which could be used  to query the
  3167.      user for a search string.
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.                                                                     57
  3178.  
  3179.  
  3180.  
  3181.  
  3182.      DiaLogic
  3183.  
  3184.  
  3185.        Note:
  3186.           We   have   provided  a   full  sample   program  called
  3187.           EXAMPLE.BAS which  accesses a similar  dialog box  which
  3188.           we will  constructing.   You may  open this program  and
  3189.           study it as you  read the tutorial below.  This  program
  3190.           accesses  a   template  which  is  on  the  distribution
  3191.           diskette   as  SEARCH.DB,   and  its   help   companion,
  3192.           SEARCHH.DB.    It is  recommended that  you  manually go
  3193.           through the steps below at least once.
  3194.  
  3195.  
  3196.  
  3197.      Making a Sketch
  3198.  
  3199.  
  3200.      (A Search dialog box, similar to the one in the QB editor, is
  3201.      presented here...)
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.      It may  be useful  to sketch the  dialog box  you wish  to create
  3218.      before  you begin.  Something remotely  close to the figure above
  3219.      will be suitable  since the purpose  of the sketch  is merely  to
  3220.      serve as a prototype.
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.      58
  3228.  
  3229.  
  3230.  
  3231.  
  3232.                                                    Creating a Template
  3233.  
  3234.      Determining the Sequence
  3235.  
  3236.      You should look at your sketch to determine the best Sequence for
  3237.      the  dialog box elements.  Recall that the Sequence refers to the
  3238.      path  of  the  input  focus  when  the  user  presses  <Tab>   or
  3239.      <Shift><Tab>.  Technically, Sequence  is the order of the  dialog
  3240.      box elements in the DB() array, and this order should be arranged
  3241.      so that <Tab> transfers the input focus in a predictable  manner.
  3242.      ``Predictability''  is  usually  attained  when  pressing   <Tab>
  3243.      transfers the  input focus  in a general  ``forward'' manner  and
  3244.      pressing <Shift><Tab>  shifts it ``backward''  across the  dialog
  3245.      box elements.
  3246.  
  3247.      We shall use the following Sequence in our example:
  3248.  
  3249.        (1)   The dialog box window
  3250.        (2)   Find What: text box
  3251.        (3)   Match Upper/Lowercase check box
  3252.        (4)   Whole Word check box
  3253.        (5)   <OK> command button
  3254.        (6)   <Cancel> command button
  3255.        (7)   <Help> command button
  3256.  
  3257.      Our Sequence  implies that  if <Tab> is  pressed while  the input
  3258.      focus rests on  the Whole Word  check box, then  the input  focus
  3259.      will be transferred to the <OK> command button.  If  <Shift><Tab>
  3260.      is  pressed then  the  Match Upper/Lowercase  check  box will  be
  3261.      accessed.  Please note one of the special situations in which the
  3262.      input focus cannot fall  on the window  dialog box element:  when
  3263.      the input focus rests on <Help> then pressing <Tab>  will skip to
  3264.      the Find What text box.
  3265.  
  3266.      Notice that we've  listed the dialog box window  as Sequence (1).
  3267.      Although  the window  appears  in the  dialog  box template,  you
  3268.      should realize that the input focus cannot  fall on it.  One rule
  3269.      you should  keep in  mind  is that  the dialog  box element  with
  3270.      Sequence number one for every template is always the window.
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.                                                                     59
  3277.  
  3278.  
  3279.  
  3280.  
  3281.      DiaLogic
  3282.  
  3283.      Copying & Pasting
  3284.  
  3285.      We recommend  keeping dialog  box templates  in an  include file.
  3286.      This not only  keeps them from cluttering your  source files, but
  3287.      also allows you to use them in other programs.
  3288.  
  3289.      The easiest  way to create an include file  is to access the File
  3290.      Create pull-down menu choice (if you are using QuickBASIC version
  3291.      4.5 or  later you must  turn on the  Full Menus feature  from the
  3292.      Options menu).  QuickBASIC will then ask for the name and type of
  3293.      file you wish to create (it uses a dialog  box for this!).  Enter
  3294.      SEARCH.DB  as the  name.   Be  sure that  the  Include option  is
  3295.      marked.  When you are finished, press <Enter>.  You may  now edit
  3296.      your new file.
  3297.  
  3298.      QuickBASIC allows you to view two different files simultaneously.
  3299.      In order  to do  this you  must first  split the  current window.
  3300.      This is accomplished by executing the View Split option from  the
  3301.      main menu.   (To undo  the split  later simply  execute the  same
  3302.      command.)  Once there are two edit  windows on the screen you may
  3303.      switch the cursor between them  and QuickBASIC's Immediate Window
  3304.      by pressing <F6> or <Shift><F6>.
  3305.  
  3306.      Our  purpose  for  splitting   the  window  is  to  display   the
  3307.      TEMPLATE.DOC file in one part of the display and SEARCH.DB in the
  3308.      other.  Having both on-screen will allow you to copy & paste from
  3309.      the generic TEMPLATE.DOC template to your own SEARCH.DB template.
  3310.  
  3311.      Place the cursor  in the upper-half  of the  screen.  Then,  load
  3312.      TEMPLATE.DOC as a document  using the File  Load option from  the
  3313.      main menu.  Scroll down until you see the following line:
  3314.  
  3315.        DB(Level%, 1).Code = 1         'Window Code
  3316.  
  3317.      This is  the first  array assignment  for the  window dialog  box
  3318.      element which has a DBE code of 1 (see page 14).
  3319.  
  3320.  
  3321.  
  3322.  
  3323.  
  3324.  
  3325.      60
  3326.  
  3327.  
  3328.  
  3329.  
  3330.                                                         Creating a Template
  3331.  
  3332.      You   should  select  the  text  from  DB(Level%,  1).Code  =  to
  3333.      DB(Level%, 1).NumberOne  =  by  using the  arrow  keys  while the
  3334.      <Shift> key  is held  down.   Once  the entire  text is  properly
  3335.      selected, let go of  the keys.  Then press  <Ctrl><Insert>.  This
  3336.      last key sequence copies the selected (highlighted) text onto the
  3337.      QuickBASIC clipboard.
  3338.  
  3339.      You may  now press <F6>  until the cursor rests  in the SEARCH.DB
  3340.      window.   Position the cursor and  press <Shift><Insert> to paste
  3341.      the contents  of the clipboard.   The text you  selected from the
  3342.      generic  template should appear (sometimes  there is a delay when
  3343.      copying or pasting).
  3344.  
  3345.      Our process of  selecting text with <Shift><arrow>,  copying text
  3346.      with <Ctrl><Insert>, and inserting  text with <Shift><Insert>  is
  3347.      the copy & paste operation to which we referred earlier.   Such a
  3348.      method is highly-suggested whenever  you need to create  a dialog
  3349.      box template.
  3350.  
  3351.      The remaining copy & paste operations are straightforward: simply
  3352.      continue  the  process   until  all  seven  dialog   box  element
  3353.      definitions  are  properly  copied.   Since  the  window template
  3354.      definition already  has  been transferred,  only these  remaining
  3355.      elements must be copied:
  3356.  
  3357.        *  one text box
  3358.        *  two check boxes
  3359.        *  three command buttons
  3360.  
  3361.      The text box generic template array assignments may be copied  in
  3362.      a  manner  exactly  like  the  window.    Simply  scroll  through
  3363.      TEMPLATE.DOC  until you  see DB().Code =  2, which  signifies the
  3364.      beginning of the text  box array assignments.   Copy & paste  all
  3365.      the text  box assignments into  the SEARCH.DB template  using the
  3366.      same process as for the window.
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.                                                                     61
  3375.  
  3376.  
  3377.  
  3378.  
  3379.      DiaLogic
  3380.  
  3381.      At this point  two check boxes and three command  buttons must be
  3382.      appended  to  the SEARCH.DB  template.   These  transfers  may be
  3383.      accomplished  by  only  two  copy operations.    Copy  the  array
  3384.      assignments  grouped  with  the  check  box, beginning  with  the
  3385.      assignment DB().Code =  4.  Transfer the cursor  to the SEARCH.DB
  3386.      template and  press <Shift><Insert> twice.  Notice that two check
  3387.      box array  assignments have  been pasted.   Thus, once  the array
  3388.      assignments for a dialog  box element have  been copied onto  the
  3389.      clipboard they may  be pasted as many times  as needed.  It  is a
  3390.      good  practice to  leave  a  blank line  between  each DBE  in  a
  3391.      template.  This will enhance readability.
  3392.  
  3393.      You may finish the  copy & paste  exercise by transferring  three
  3394.      command button definitions, which begin with DB().Code = 7 in the
  3395.      generic template.
  3396.  
  3397.      You now have all  the information from  the generic template  for
  3398.      the Search dialog  box.  You should  save your work so  far using
  3399.      the File  Save pull-down menu  option while the cursor  is in the
  3400.      SEARCH.DB edit window.  At this time you may wish to ``un-split''
  3401.      the  SEARCH.DB  edit window  since  most  upcoming work  will  be
  3402.      concerned with this file. 
  3403.  
  3404.      Your job now  involves giving a value  to each DB() element.   In
  3405.      order  to do this you may need to refer to Appendix A: Dialog Box
  3406.      Elements.  Also, it may be desirable to turn QuickBASIC's  Syntax
  3407.      Checking feature off (by using the pull-down menu system), and to
  3408.      insure that  the Overwrite  insert mode  is on  (by pressing  the
  3409.      <Ins> key until the cursor becomes full-size). 
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.      62
  3424.  
  3425.  
  3426.  
  3427.  
  3428.                                                    Creating a Template
  3429.  
  3430.      Making the Assignments
  3431.  
  3432.      Let's begin  with the  window definition.   The  empty definition
  3433.      from the generic template will appear something like this:
  3434.  
  3435.        DB(Level%, 1).Code = 1
  3436.        DB(Level%, 1).Y =     
  3437.        DB(Level%, 1).X =     
  3438.        DB(Level%, 1).Height =
  3439.        DB(Level%, 1).Wdth =  
  3440.        DB(Level%, 1).BorderType =
  3441.        DB(Level%, 1).PrimaryColor =
  3442.        DB(Level%, 1).WindowColor = 
  3443.        DB(Level%, 1).Text =        
  3444.        DB(Level%, 1).TextColor =   
  3445.        DB(Level%, 1).SecondaryColor =
  3446.        DB(Level%, 1).NumberOne =     
  3447.  
  3448.      Notice  that DB().Code is already defined and that all subscripts
  3449.      have the second  dimension already  set to  1.  We  were able  to
  3450.      complete the Sequence subscripts only for the window since it  is
  3451.      always the first  dialog box  element in a  template.  The  first
  3452.      dimension, the  box Level  number,  will remain  as the  variable
  3453.      Level% for now.
  3454.  
  3455.      You  may use the QuickBASIC  editor to assign  values to the DB()
  3456.      array elements.  We shall make both Y and X equal to 0 because we
  3457.      want the  box automatically  centered on  the screen  when it  is
  3458.      displayed.  Height will be 11 and width will be 60.
  3459.  
  3460.      For  the window DB().BorderType  allows us  to define  the border
  3461.      style and an explode option.  Since we do not  wish the window to
  3462.      explode we'll  set border  type to 1,  which represents  a single
  3463.      outline (see Borders on page 26).
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.                                                                     63
  3473.  
  3474.  
  3475.  
  3476.  
  3477.      DiaLogic
  3478.  
  3479.      DB().PrimaryColor controls the  border color  for the window  and
  3480.      also  allows a shadow to  be drawn if  the value of  the color is
  3481.      negative.  Since we do want a shadow we'll set  DB().PrimaryColor
  3482.      to   -112.      DiaLogic   will  use   the   absolute   value  of
  3483.      DB().PrimaryColor to determine the color  (see Appendix D: Dialog
  3484.      Software Color Chart).
  3485.  
  3486.      DB().WindowColor is  the color  of the inside  window space.   We
  3487.      wish this  to be  consistent with the  border so  we'll use  112.
  3488.      However,  we also  want a  bottom  horizontal line  to cover  the
  3489.      command buttons.  For  this reason we'll use the negative value -
  3490.      112 since a negative window color produces a bottom divider line.
  3491.  
  3492.      DB().Text will produce a centered window title.  For this  dialog
  3493.      box we'll  use ``Search''  as the title.   DB().TextColor  is the
  3494.      color of the title.  We'll  use 112.  DB().SecondaryColor is  the
  3495.      color of the horizontal line.  We'll use 112 for that too.
  3496.  
  3497.      Finally, DB().NumberOne holds  the number  of screen lines  which
  3498.      will be present when the dialog box is displayed.  We will use 25
  3499.      for this value since the screen will be in 25-line mode.
  3500.  
  3501.      When  you  are  finished  your  template  should  look  like  the
  3502.      following:
  3503.  
  3504.        DB(Level%, 1).Code = 1
  3505.        DB(Level%, 1).Y = 0
  3506.        DB(Level%, 1).X = 0   
  3507.        DB(Level%, 1).Height = 11
  3508.        DB(Level%, 1).Wdth = 60
  3509.        DB(Level%, 1).BorderType = 1
  3510.        DB(Level%, 1).PrimaryColor = -112
  3511.        DB(Level%, 1).WindowColor = -112
  3512.        DB(Level%, 1).Text = "Search" 
  3513.        DB(Level%, 1).TextColor = 112 
  3514.        DB(Level%, 1).SecondaryColor = 112
  3515.        DB(Level%, 1).NumberOne = 25
  3516.  
  3517.  
  3518.  
  3519.  
  3520.  
  3521.      64
  3522.  
  3523.  
  3524.  
  3525.  
  3526.                                                    Creating a Template
  3527.  
  3528.      DiaLogic will use  all the information above when  displaying the
  3529.      dialog box  window and  anything about  the window  (such as  its
  3530.      color, location,  size, etc.) can  be altered simply  by changing
  3531.      the a value in the DB() array.
  3532.  
  3533.      We will  continue  in this  manner  until all  the  elements  are
  3534.      assigned values.   Keep in mind that although  this is no doubt a
  3535.      tedious process, once a dialog box template is created  it may be
  3536.      used in any program with no modification.
  3537.  
  3538.      The next element  is the text box.   It should use  the following
  3539.      values, and you will have to  add the Sequence number "2" to  the
  3540.      second DB() array subscript (this corresponds to the DBE Sequence
  3541.      we had established earlier, on page 59):
  3542.  
  3543.        DB(Level%, 2).Code = 2
  3544.        DB(Level%, 2).Y = 2
  3545.        DB(Level%, 2).X = 14
  3546.        DB(Level%, 2).Wdth = 44
  3547.        DB(Level%, 2).BorderType = 1
  3548.        DB(Level%, 2).PrimaryColor = 112
  3549.        DB(Level%, 2).WindowColor = 112
  3550.        DB(Level%, 2).SelectedColor = 7
  3551.        DB(Level%, 2).TextY = 3
  3552.        DB(Level%, 2).TextX = 3
  3553.        DB(Level%, 2).Text = "~Find What:"
  3554.        DB(Level%, 2).TextColor = 112
  3555.        DB(Level%, 2).KeyColor = 127
  3556.        DB(Level%, 2).TextString = ""
  3557.        DB(Level%, 2).ItemLength = 50
  3558.        DB(Level%, 2).Default = 0
  3559.  
  3560.      Remember,  a  character  which follows  a  tilde  will  become an
  3561.      Alt-key when the  dialog box is run.  Thus,  pressing <Alt>F will
  3562.      access  the  check  box  defined  above.    Further,  we've  left
  3563.      DB().TextString equal  to null  since we  do not  wish a  default
  3564.      string to be specified.
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.                                                                     65
  3571.  
  3572.  
  3573.  
  3574.  
  3575.      DiaLogic
  3576.  
  3577.      The Match Upper/Lowercase check box is defined below:
  3578.  
  3579.        DB(Level%, 3).Code = 4
  3580.        DB(Level%, 3).Y = 6
  3581.        DB(Level%, 3).X = 3
  3582.        DB(Level%, 3).PrimaryColor = 112
  3583.        DB(Level%, 3).SelectedColor = 112
  3584.        DB(Level%, 3).TextY = 6
  3585.        DB(Level%, 3).TextX = 7
  3586.        DB(Level%, 3).Text = "~Match Upper/Lower Case"
  3587.        DB(Level%, 3).TextColor = 112
  3588.        DB(Level%, 3).KeyColor = 127
  3589.        DB(Level%, 3).StarColor = 113
  3590.        DB(Level%, 3).Default = -1
  3591.  
  3592.      The next check box is defined as follows:
  3593.  
  3594.        DB(Level%, 4).Code = 4
  3595.        DB(Level%, 4).Y = 7
  3596.        DB(Level%, 4).X = 3
  3597.        DB(Level%, 4).SecondaryColor = 112
  3598.        DB(Level%, 4).SelectedColor = 112
  3599.        DB(Level%, 4).TextY = 7
  3600.        DB(Level%, 4).TextX = 7
  3601.        DB(Level%, 4).Text = "~Whole Word"
  3602.        DB(Level%, 4).TextColor = 112
  3603.        DB(Level%, 4).KeyColor = 127
  3604.        DB(Level%, 4).StarColor = 113
  3605.        DB(Level%, 4).Default = 0
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.      66
  3620.  
  3621.  
  3622.  
  3623.  
  3624.                                                    Creating a Template
  3625.  
  3626.      The <OK> command button is defined as follows:
  3627.  
  3628.        DB(Level%, 5).Code = 7
  3629.        DB(Level%, 5).Y = 10
  3630.        DB(Level%, 5).X = 10
  3631.        DB(Level%, 5).Text = "OK"
  3632.        DB(Level%, 5).PrimaryColor = 112
  3633.        DB(Level%, 5).WindowColor = 112 
  3634.        DB(Level%, 5).SelectedColor = 7
  3635.        DB(Level%, 5).KeyColor = 127
  3636.        DB(Level%, 5).SecondaryColor = 127
  3637.        DB(Level%, 5).Default = -1
  3638.        DB(Level%, 5).TextString = CHR$(13)
  3639.  
  3640.      The command  button above  will be  the default  since we've  set
  3641.      DB().Default to -1.   This implies that  <OK> will be  active and
  3642.      thus highlighted at  all times unless  another command button  is
  3643.      accessed.  It is customary to indicate  an <OK> command button as
  3644.      the default.   Further, we have set DB().TextString  to CHR$(13),
  3645.      the  ASCII character for <Enter>.   Therefore, DiaLogic will make
  3646.      Ky$ equal to CHR$(13) if the <OK> command button is pushed.
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.  
  3654.  
  3655.  
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.                                                                     67
  3669.  
  3670.  
  3671.  
  3672.  
  3673.      DiaLogic
  3674.  
  3675.      The <Cancel> and  <Help> command buttons and the  last dialog box
  3676.      element in the template are defined as follows:
  3677.  
  3678.  
  3679.        DB(Level%, 6).Code = 7
  3680.        DB(Level%, 6).Y = 10
  3681.        DB(Level%, 6).X = 24
  3682.        DB(Level%, 6).Text = "Cancel"
  3683.        DB(Level%, 6).PrimaryColor = 112
  3684.        DB(Level%, 6).WindowColor = 112
  3685.        DB(Level%, 6).SelectedColor = 7
  3686.        DB(Level%, 6).KeyColor = 127
  3687.        DB(Level%, 6).SecondaryColor = 127
  3688.        DB(Level%, 6).Default = 0
  3689.        DB(Level%, 6).TextString = CHR$(27)
  3690.  
  3691.        DB(Level%, 7).Code = 7
  3692.        DB(Level%, 7).Y = 10
  3693.        DB(Level%, 7).X = 43
  3694.        DB(Level%, 7).Text = "~Help"
  3695.        DB(Level%, 7).PrimaryColor = 112
  3696.        DB(Level%, 7).WindowColor = 112
  3697.        DB(Level%, 7).SelectedColor = 7
  3698.        DB(Level%, 7).KeyColor = 127
  3699.        DB(Level%, 7).NumberOne = 127
  3700.        DB(Level%, 7).Default = 0
  3701.        DB(Level%, 7).TextString = CHR$(0) + CHR$(59)
  3702.  
  3703.        DB(Level%, 8).Code = 0      '<-- very important!
  3704.  
  3705.  
  3706.      The command buttons above are similar to the <OK> command button.
  3707.      Notice that  DB().Default is set  to 0 for  both.  The  reason is
  3708.      that we've already assigned the default  button.  If we had tried
  3709.      to  define  <Help> as  the  default  in  addition to  <OK>,  then
  3710.      DiaLogic would  use the command  button with the  higher Sequence
  3711.      and would therefore accept <Help> as the default.
  3712.  
  3713.  
  3714.  
  3715.  
  3716.  
  3717.      68
  3718.  
  3719.  
  3720.  
  3721.  
  3722.                                                    Creating a Template
  3723.  
  3724.      We  have associated the  <Esc> key (CHR$(27))  with <Cancel>, and
  3725.      the <F1> key (CHR$(0)  + CHR$(59)) with  <Help> so that  DiaLogic
  3726.      will return the appropriate key in Ky$.
  3727.  
  3728.      Observe that <Help> has an Alt-key.  Neither the <Cancel> nor the
  3729.      <OK> command buttons, by convention, contains an Alt-key.
  3730.  
  3731.      Finally, the most important thing about the end of  a template is
  3732.      that the last Sequence number must assign DB().Code to 0 !
  3733.  
  3734.      At this point you have completed your first dialog box  template.
  3735.      Congratulations!  You should  now use  the File  Save option  and
  3736.      remember that  your  template is  being  saved as  the  SEARCH.DB
  3737.      include file.
  3738.  
  3739.      Before going on, please examine the new template presented below.
  3740.      This template defines the Help dialog box which will be presented
  3741.      when the user requests  help while using  the Search dialog  box.
  3742.      If  you  wish to  construct  this  template  using the  procedure
  3743.      described  for the  Search dialog  box,  then please  save it  as
  3744.      SEARCHH.DB.  Alternatively, you can later use this template since
  3745.      it exists on the distribution diskette as SEARCHH.DB.
  3746.  
  3747.        DB(Level%, 1).Code = 1              
  3748.        DB(Level%, 1).Y = 10                 
  3749.        DB(Level%, 1).X = 4               
  3750.        DB(Level%, 1).Height = 10           
  3751.        DB(Level%, 1).Wdth = 35            
  3752.        DB(Level%, 1).BorderType = 1       
  3753.        DB(Level%, 1).PrimaryColor = -112   
  3754.        DB(Level%, 1).WindowColor = -112     
  3755.        DB(Level%, 1).Text = "Help"         
  3756.        DB(Level%, 1).TextColor = 112       
  3757.        DB(Level%, 1).SecondaryColor = 112
  3758.        DB(Level%, 1).NumberOne = 25
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.                                                                     69
  3767.  
  3768.  
  3769.  
  3770.  
  3771.      DiaLogic
  3772.  
  3773.        LB(1).Text = "This is an example of a Help"
  3774.        LB(2).Text = "dialog box.  This help text"
  3775.        LB(3).Text = "actually is contained in a"
  3776.        LB(4).Text = "list box!"
  3777.        DB(Level%, 2).Code = 3               
  3778.        DB(Level%, 2).Y = 2                   
  3779.        DB(Level%, 2).X = 2                   
  3780.        DB(Level%, 2).Height = 4             
  3781.        DB(Level%, 2).Wdth = 1               
  3782.        DB(Level%, 2).WindowColor = 112      
  3783.        DB(Level%, 2).PrimaryColor = 112     
  3784.        DB(Level%, 2).SecondaryColor = 112
  3785.        DB(Level%, 2).SelectedColor = -1     
  3786.        DB(Level%, 2).StarColor = 112        
  3787.        DB(Level%, 2).ItemLength = 30        
  3788.        DB(Level%, 2).KeyColor = 0           
  3789.        DB(Level%, 2).BorderType = 0         
  3790.        DB(Level%, 2).Link = 0               
  3791.        DB(Level%, 2).TextY = 0              
  3792.        DB(Level%, 2).TextX = 0              
  3793.        DB(Level%, 2).TextColor = 112        
  3794.        DB(Level%, 2).NumberOne = 1          
  3795.        DB(Level%, 2).NumberTwo = 4          
  3796.        DB(Level%, 2).Default = 0            
  3797.  
  3798.        DB(Level%, 3).Code = 7               
  3799.        DB(Level%, 3).Y = 9
  3800.        DB(Level%, 3).X = 15                 
  3801.        DB(Level%, 3).Text = "~OK"           
  3802.        DB(Level%, 3).PrimaryColor = 112     
  3803.        DB(Level%, 3).WindowColor = 127      
  3804.        DB(Level%, 3).SelectedColor = 7      
  3805.        DB(Level%, 3).KeyColor = 127         
  3806.        DB(Level%, 3).SecondaryColor = 127        
  3807.        DB(Level%, 3).Default = -1
  3808.        DB(Level%, 3).TextString = CHR$(13)
  3809.  
  3810.        DB(Level%, 4).Code = 0
  3811.  
  3812.  
  3813.  
  3814.  
  3815.      70
  3816.  
  3817.  
  3818.  
  3819.  
  3820.                                                    Creating a Template
  3821.  
  3822.      This template  demonstrates a way  to use  a list box  to present
  3823.      paragraph-oriented text.   This  list box  is neither linked  nor
  3824.      does it select  an element.  When  DB().SelectedColor is -1 for a
  3825.      list box,  a highlight bar will not be  visible.  Also, this list
  3826.      box has  a Sequence of 2 and will  access elements 1 through 5 of
  3827.      the  LB()  array  since  DB().NumberOne  and  DB().NumberTwo  are
  3828.      defined for these values.
  3829.  
  3830.      When the  help dialog  box is  used it  would most  likely be  at
  3831.      Level 2, which will allow it to be drawn ``on top of'' the Search
  3832.      dialog box.  The  method for doing this is discussed  in Part VI:
  3833.      Advanced Topics.
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841.  
  3842.  
  3843.  
  3844.  
  3845.  
  3846.  
  3847.  
  3848.  
  3849.  
  3850.  
  3851.  
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.  
  3858.  
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.                                                                     71
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.                                   DiaLogic
  3878.  
  3879.  
  3880.                                   PART IV
  3881.                             GENERATING A DIALOG BOX
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.                                                Generating a Dialog Box
  3889.  
  3890.      In this section  we explain how to  use dialog boxes in  your own
  3891.      programs, culminating with  a full program to generate the Search
  3892.      dialog box created in Part III: Creating a Template.
  3893.  
  3894.      The call to DiaLogic allows you to  do several things to a dialog
  3895.      box depending on  the arguments used.  One  argument we mentioned
  3896.      earlier called Action% will become very important when generating
  3897.      dialog  boxes:  it determines  what will  happen after  the call.
  3898.      Briefly, the Action allows you to:
  3899.  
  3900.         * display a dialog box from its template
  3901.         * remove a dialog box from the screen
  3902.         * stack a dialog box over an existing one
  3903.         * update the elements within a dialog box
  3904.         * process the dialog box alternately with the calling
  3905.           program
  3906.  
  3907.      It should be clear that Action allows you to display dialog boxes
  3908.      in different ways  and, as you will soon  discover, distinguishes
  3909.      single-tasking from multi-tasking dialog boxes.
  3910.  
  3911.      Preparing for the Call
  3912.  
  3913.      While all  the steps need  not be taken,  there are a  few things
  3914.      which  should be  considered when  preparing  to make  a call  to
  3915.      DiaLogic.  These steps are discussed next.
  3916.  
  3917.      *  Including DIALOGIC.BI
  3918.      *  Initializing the Mouse
  3919.      *  REDIMing DiaLogic's Arrays
  3920.      *  Setting the Level
  3921.      *  Including the Dialog Box Template
  3922.      *  Setting the Action
  3923.      *  Setting the Focus
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.                                                                     73
  3933.  
  3934.  
  3935.  
  3936.  
  3937.      DiaLogic
  3938.  
  3939.      Including DIALOGIC.BI
  3940.  
  3941.      It is important  to place following  statement at the top  of the
  3942.      calling program:
  3943.  
  3944.        '$INCLUDE: 'DIALOGIC.BI'
  3945.  
  3946.      This  makes   available  to   QuickBASIC  the  DiaLogic   DECLARE
  3947.      statements for  both the assembler  and BASIC  routines, and  the
  3948.      TYPE declarations for both the DB() and LB() arrays.  
  3949.  
  3950.      Initializing the Mouse
  3951.  
  3952.      Before first  using DiaLogic the calling program  should check to
  3953.      see if a mouse is present  and, if so, it should reset the  mouse
  3954.      driver software  to  its default  values.   We've  given  you  an
  3955.      assembler  subroutine  called   InitMouse  in  DIALOGIC.QLB   for
  3956.      initializing the mouse driver:
  3957.  
  3958.        DECLARE SUBROUTINE InitMouse(There%)
  3959.        CALL InitMouse(There%)
  3960.  
  3961.      If a mouse is present then There% will be set to -1.  If no mouse
  3962.      is installed then There%  will be 0.  In order for  a mouse to be
  3963.      operational both the  mouse hardware and software  driver must be
  3964.      available to the computer.
  3965.  
  3966.      Because  InitMouse  resets  the mouse  driver  values  (the mouse
  3967.      cursor  color, its travel range  and sensitivity, etc), it should
  3968.      probably be called only once at the start of a program.
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.      74
  3982.  
  3983.  
  3984.  
  3985.  
  3986.                                                Generating a Dialog Box
  3987.  
  3988.      After initializing the mouse you should insure that its cursor is
  3989.      visible.  We've given you two assembler routines which should  be
  3990.      used for  this purpose.  One is  called ShowCursor, and the other
  3991.      is TextCursor.  Consider the following program fragment:
  3992.  
  3993.        DECLARE SUBROUTINE ShowCursor()
  3994.        DECLARE SUBROUTINE TextCursor(FG%, BG%)
  3995.        CALL ShowCursor()
  3996.        FG% = 0
  3997.        BG% = 4
  3998.        CALL TextCursor(FG%, BG%)
  3999.  
  4000.      ShowCursor needs  no  arguments and,  on most  machines, it  will
  4001.      reveal the mouse  cursor on the screen.   TextCursor is necessary
  4002.      when  this does not work, and we recommend using both routines to
  4003.      insure that  the mouse  cursor can be  seen.  TextCursor  is more
  4004.      powerful than  ShowCursor since  it allows you  to set  the mouse
  4005.      cursor's  foreground  and  background  colors  in  FG%  and  BG%,
  4006.      respectively.  We  suggest using 0 for  FG% and 4 for  BG%, which
  4007.      produces a cursor like the one in QuickBASIC's environment.
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.                                                                     75
  4031.  
  4032.  
  4033.  
  4034.  
  4035.      DiaLogic
  4036.  
  4037.      In many cases a calling program will need to print information on
  4038.      the screen.  It is necessary to  turn the mouse cursor off before
  4039.      printing.   You  may do  this  using HideCursor  but  you  should
  4040.      remember to issue a complimentary ShowCursor call.  HideCursor is
  4041.      declared and called like this:
  4042.  
  4043.        DECLARE SUBROUTINE HideCursor()
  4044.        CALL HideCursor()
  4045.  
  4046.      HideCursor, like ShowCursor, requires no arguments.
  4047.  
  4048.  
  4049.  
  4050.        Note:
  4051.           If HideCursor  is not used before printing on the screen
  4052.           then the background  attribute for the character printed
  4053.           in the mouse cursor's location may not be correct.   The
  4054.           result is a mouse cursor ``imprint'' which  is generally
  4055.           not acceptable.
  4056.  
  4057.  
  4058.  
  4059.      The  DECLARE  statements  were  shown  immediately  before  their
  4060.      respective   calling  syntaxes   in   the  above   examples   for
  4061.      documentation purposes:  they should always be at the very top of
  4062.      the calling  program's main module.  But these DECLARE statements
  4063.      are  present  in the  include  file DIALOGIC.BI.    Thus, if  you
  4064.      include DIALOGIC.BI  at the top of your program, then the DECLARE
  4065.      statements will  be available  and therefore  do not  have to  be
  4066.      explicitly entered.
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.      76
  4080.  
  4081.  
  4082.  
  4083.  
  4084.                                                Generating a Dialog Box
  4085.  
  4086.      Hence,  if a mouse is available the assembler routines InitMouse,
  4087.      ShowCursor,  TextCursor,  and  HideCursor   should  provide  full
  4088.      control  over  its  initialization  and  its cursor's  color  and
  4089.      visibility.    If a  mouse  is  not  present then  DiaLogic  will
  4090.      function very well using the keyboard alone.
  4091.  
  4092.      It is  not necessary  to use  any of  these mouse  initialization
  4093.      steps if no mouse is present.   If the calling program will never
  4094.      make use of a mouse then you may consider removing  mouse-related
  4095.      code from DIALOGIC.BAS.  This process is discussed in Appendix B:
  4096.      Modifying DIALOGIC.BAS.
  4097.  
  4098.      REDIMing DiaLogic's Arrays
  4099.  
  4100.      Before you include  your dialog box template and  before you make
  4101.      any calls to  DiaLogic you must REDIM  two arrays.   These arrays
  4102.      will hold the  dialog box template  and any list  box items.   We
  4103.      suggest using  dynamic arrays so  that they may  be redimensioned
  4104.      using  the REDIM  statement as  needed  by your  program (if  you
  4105.      intend to use huge arrays, please see the note on page 94):
  4106.  
  4107.        '$DYNAMIC
  4108.        REDIM DB(2, 30) AS DialogType
  4109.        REDIM LB(50) AS ListType
  4110.  
  4111.      The preceding example  dimensions DB() in such a  way that memory
  4112.      is  set aside  for up to  2 dialog  boxes having a  maximum of 30
  4113.      elements each.  Recall that the first subscript in DB() refers to
  4114.      the dialog box Level number, while the second subscript refers to
  4115.      the Sequence  of  a particular  dialog  box element.    When  you
  4116.      initialize DB() you must insure that it  is dimensioned correctly
  4117.      for both the maximum number of dialog  boxes to be stacked on the
  4118.      screen  at one  time (the  Level) and  the number  of  dialog box
  4119.      elements (i.e., the  highest Sequence number) with  which it will
  4120.      be used.
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.                                                                     77
  4129.  
  4130.  
  4131.  
  4132.  
  4133.      DiaLogic
  4134.  
  4135.      The LB() array is dimensioned here at a conservative 50 elements.
  4136.      This means that  a single list  box can contain  a maximum of  50
  4137.      items.   The exact number used in  dimensioning this array may be
  4138.      tailored to your  specific needs.  If you use no  list boxes in a
  4139.      dialog box you still must at least  define the array, but you may
  4140.      specify 0 elements like this:
  4141.  
  4142.        REDIM LB(0) AS ListType
  4143.  
  4144.      This way, a compiler error will not be generated and, at the same
  4145.      time, no  memory will  be wasted  when allocating  space for  the
  4146.      array.
  4147.  
  4148.      Setting the Level
  4149.  
  4150.      The Level is represented  by the variable  Level% and allows  the
  4151.      DB() array to  hold more than  one template at  once.  When  more
  4152.      than  one  Level is  present  dialog  boxes  may be  stacked  and
  4153.      unstacked.    DiaLogic is  smart  because  it  preserves all  the
  4154.      choices on  a dialog box before it allows a new one to be stacked
  4155.      on  top of  it.  This  feature enables an  overlaying dialog box,
  4156.      such as Dialog Box No. 2 below, to be removed from Dialog Box No.
  4157.      1  beneath it.   Thus,  when  DiaLogic is  called to  re-activate
  4158.      Dialog Box No. 1 it is able to  resume processing precisely where
  4159.      it had been.
  4160.  
  4161.  
  4162.                                             
  4163.                       (Figure shows one box atop another.)                 
  4164.          
  4165.                                                    
  4166.                                         
  4167.           Figure 8: Stacked dialog boxes at two Levels
  4168.  
  4169.  
  4170.  
  4171.      78
  4172.  
  4173.  
  4174.  
  4175.  
  4176.                                                Generating a Dialog Box
  4177.  
  4178.      Stacked  dialog boxes produce an aesthetic screen.  However, each
  4179.      dialog box  must be  retained in the  DB() array  and, therefore,
  4180.      stacked dialog boxes require more memory.
  4181.  
  4182.      Recall that the array subscripts in the template created in  Part
  4183.      III: Creating a Template remain like this:
  4184.  
  4185.        DB(Level%, 1).Code = 1
  4186.        DB(Level%, 2).X = 0
  4187.        DB(Level%, 3).Y = 0
  4188.           .
  4189.           .
  4190.           .
  4191.  
  4192.      Therefore, it is  up to you to assign a positive integer value to
  4193.      the variable  Level% before  including the  dialog box  template.
  4194.      The example below shows a dialog  box template which is being set
  4195.      at Level 1.  Notice that the Level assignment statement  precedes
  4196.      the  template,  so  that  QuickBASIC   compiles  the  DB()  array
  4197.      assignments using 1 as the value of the first subscript:
  4198.  
  4199.        Level% = 1
  4200.        '$INCLUDE: 'TEMPLATENAME.DB'
  4201.        <<DB(Level%, 1).Code = 1>>    
  4202.        <<DB(Level%, 2).X = 0>>       
  4203.        <<DB(Level%, 3).Y = 0>>       
  4204.           .
  4205.           .
  4206.           .
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.                                                                     79
  4221.  
  4222.  
  4223.  
  4224.  
  4225.      DiaLogic
  4226.  
  4227.      The  previous program  fragment will  work  the same  way as  the
  4228.      fragment below which states the  array assignments explicitly and
  4229.      does not use an include file:
  4230.  
  4231.  
  4232.        DB(1, 1).Code = 1
  4233.        DB(1, 2).X = 0
  4234.        DB(1, 3).Y = 0
  4235.           .
  4236.           .
  4237.           .
  4238.  
  4239.  
  4240.  
  4241.        Note: 
  4242.           The reason you should not replace Level% with 1  in your
  4243.           template files is  that the template would then only  be
  4244.           usable at  Level 1.  If  you wished to  stack the dialog
  4245.           box  defined  by the  template onto  an  existing dialog
  4246.           box, you  would require  a Level  of 2.   If ``1''  were
  4247.           hard-coded  in  the  template  definition  you would  be
  4248.           required  to  change  all  subscripts for  DB()  in  the
  4249.           template  to ``2''.   For  this reason,  hard-coding the
  4250.           Level subscript  for the DB() array in template files is
  4251.           not recommended.
  4252.  
  4253.  
  4254.  
  4255.      Including the Dialog Box Template
  4256.  
  4257.      Including  a template, such as  the SEARCH.DB dialog box template
  4258.      we created in Part  III: Creating a Template, is  a simple matter
  4259.      of using the following command:
  4260.  
  4261.        '$INCLUDE: 'TEMPLATENAME.DB'
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.      80
  4270.  
  4271.  
  4272.  
  4273.  
  4274.                                                Generating a Dialog Box
  4275.  
  4276.      Setting the Action
  4277.  
  4278.      Most of the  dialog boxes you  create will simply query  the user
  4279.      first and  then return to  the calling program.   These types  of
  4280.      dialog  box  are referred  to  as single-tasking  since  only one
  4281.      program (i.e., DiaLogic) runs while the dialog box is active.
  4282.  
  4283.      More advanced dialog boxes are distinguished  by their ability to
  4284.      return to  the  calling program  after  or even  while  they  are
  4285.      displayed.  These  dialog boxes are referred to  as multi-tasking
  4286.      since  at  least two  programs  (i.e., DiaLogic  and  the calling
  4287.      program) are alternately executed while the dialog box is active.
  4288.  
  4289.      In terms  of  tasking  abilities,  the  type  of  dialog  box  is
  4290.      determined  by the  Action%  argument in  the  call to  DiaLogic.
  4291.      Page 82 shows that Action has 8 values ranging from 0 to 7.  When
  4292.      Action is 0, for example, the dialog box is displayed and removed
  4293.      using a  single  call.   Other  Action values  allow  for  higher
  4294.      complexity  however  they  require  multiple  calls.    Since  an
  4295.      understanding of Action  is extremely  important we have  devoted
  4296.      Part VI: Advanced Topics towards demonstrating its use.  
  4297.  
  4298.  
  4299.        Note:
  4300.           It may be helpful  to know that these Action values  are
  4301.           similar  to   those  used   in  other   Dialog  Software
  4302.           products, such as QuickPak Professional's  multi-tasking
  4303.           pull-down menu system.
  4304.  
  4305.  
  4306.  
  4307.  
  4308.  
  4309.  
  4310.  
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.                                                                     81
  4319.  
  4320.  
  4321.  
  4322.  
  4323.      DiaLogic
  4324.  
  4325.      Action%
  4326.       Value  Function
  4327.  
  4328.           0     Opens a  dialog box; gathers  information; removes the
  4329.                 dialog box from the screen.
  4330.  
  4331.           1     Opens  a  dialog  box;  immediately   returns  to  the
  4332.                 calling program with Action set to 3.
  4333.  
  4334.           2     Refreshes the contents  or status of  all text  boxes,
  4335.                 list  boxes,  check  boxes,  and  option  buttons   by
  4336.                 examining the DB() array.
  4337.  
  4338.           3     Calls  DiaLogic  in  a  multi-tasking  (polled)  mode.
  4339.                 Action remains 3  until a key is pressed  or the mouse
  4340.                 is used, in which case Action becomes 4.
  4341.  
  4342.           4     Signals that input was received while in polled mode.
  4343.  
  4344.           5     Closes a dialog box by removing it from the screen.
  4345.  
  4346.           6     Opens a dialog box;  gathers information; and  returns
  4347.                 to  the calling program.   The  dialog box  remains on
  4348.                 the screen until action 5  is used.  Alternatively,  a
  4349.                 new dialog  box can be  stacked using the  next Level;
  4350.                 once  it is  closed and  removed, the  Action-6 dialog
  4351.                 box  may  be reactivated  using Action  2  followed by
  4352.                 Action 7.
  4353.  
  4354.           7     Terminates  the multi-tasking action.   Once used, the
  4355.                 dialog box  will resume  execution as  if it  had been
  4356.                 called with Action=6.
  4357.  
  4358.  
  4359.      Our example in this section  will illustrate the use of Action  0
  4360.      only.   Action-0 dialog boxes  are ideal  for most  applications.
  4361.      More  complex dialog  boxes are  discussed  in Part  VI: Advanced
  4362.      Topics.
  4363.  
  4364.  
  4365.  
  4366.  
  4367.      82
  4368.  
  4369.  
  4370.  
  4371.  
  4372.                                                Generating a Dialog Box
  4373.  
  4374.      Setting the Focus
  4375.  
  4376.      Before calling DiaLogic, the argument Focus% specifies the DBE on
  4377.      which  the input focus should  rest when the  dialog box is first
  4378.      generated.  If you  set Focus to 0, then DiaLogic  will place the
  4379.      input focus on the DBE with  the lowest Sequence number which can
  4380.      receive the input focus (see Figure 2, page 14).
  4381.  
  4382.      After the call, Focus% contains the DBE on which  the input focus
  4383.      last rested.   This information is useful if  the calling program
  4384.      needs  to  know the  exact  dialog  box  element which  was  last
  4385.      accessed before control was returned to the calling program.  
  4386.  
  4387.      For example, if we created a simple dialog box which had  an <OK>
  4388.      and a <Help> command  button only, we  could assume the  template
  4389.      consists of Sequence (1) the window, (2) the <OK> command button,
  4390.      and (3) the <Help> command button.  If we wished the  input focus
  4391.      to be on <OK> when the dialog box is displayed then we would  set
  4392.      Focus% to 2,  since the <OK> button  has a Sequence number  of 2.
  4393.      Another possibility  would be  to place  the input  focus on  the
  4394.      <Help> button.   Here, we would set Focus%  to 3.  Please realize
  4395.      that, for this dialog box, if Focus% were set to 0, then the <OK>
  4396.      button would  be  the first  available  DBE and  therefore  would
  4397.      receive the input focus.
  4398.  
  4399.      Ky$
  4400.  
  4401.      The variable  Ky$ is  the only argument  which cannot be  used to
  4402.      pass  a value to  DiaLogic.  Any  initial value it  has is simply
  4403.      ignored.  However,  Ky$ becomes very useful when DiaLogic returns
  4404.      to  the calling  program.  Ky$  will always  hold a key,  such as
  4405.      <Enter>.  But the key it contains may have been either pressed on
  4406.      the keyboard or returned by  a command button.  Recall  that each
  4407.      command  button  specifies  a   key  to  which  it  is   uniquely
  4408.      associated.  This  command-button key value is  a string returned
  4409.      in Ky$.
  4410.  
  4411.      Pressing <Esc>  will  always return  CHR$(27)  in Ky$.    However
  4412.      pressing <Enter>, double-clicking on a list box item, or clicking
  4413.      on a command button will always return the command-button key for
  4414.      the active command button.
  4415.  
  4416.  
  4417.                                                                     83
  4418.  
  4419.  
  4420.  
  4421.  
  4422.      DiaLogic
  4423.  
  4424.      Making the Call
  4425.  
  4426.      The call to DiaLogic has the following syntax:
  4427.  
  4428.        CALL DiaLogic(DB(), LB(), Action%, Focus%, Ky$)
  4429.  
  4430.      At this point,  the pre-call instructions discussed  may be added
  4431.      for a resulting program segment which is something like this:
  4432.  
  4433.        DEF INT A-Z                 'recommended if possible
  4434.        '$INCLUDE: 'DIALOGIC.BI'    'include TYPE definitions
  4435.        '$DYNAMIC            'make arrays dynamic
  4436.        REDIM DB(2, 30) AS DialogType  'REDIM arrays
  4437.        REDIM LB(50) AS ListType    'REDIM arrays
  4438.        Level% = 1                  'set the Level
  4439.        '$INCLUDE: 'SEARCH.DB'      'include the template
  4440.        Action% = 0                 'set the Action
  4441.        Focus% = 0                  'set the Focus
  4442.                                    'make the call
  4443.        CALL DiaLogic(DB(), LB(), Action%, Focus%, Ky$)
  4444.  
  4445.  
  4446.      The above instructions  will generate the  Search dialog box  and
  4447.      patiently wait for input.   The first statement, DEF INT A-Z,  is
  4448.      useful if your  program can operate using integer  variables as a
  4449.      default.  In  general, this  statement can  increase a  program's
  4450.      execution speed.  Remember that the dialog box is closed when the
  4451.      user  presses  <Esc>, <Enter>,  clicks  on  a  command button  or
  4452.      double-clicks  on  a list  box item.   Once  one of  these events
  4453.      occurs, the  dialog box will  be removed from the  screen and the
  4454.      underlying image  will be  restored.  At  this point  the calling
  4455.      program regains control and may ``process'' its call to DiaLogic.
  4456.  
  4457.  
  4458.  
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.      84
  4467.  
  4468.  
  4469.  
  4470.  
  4471.                                                Generating a Dialog Box
  4472.  
  4473.      Processing the Call
  4474.  
  4475.      Processing the call consists of analyzing information returned by
  4476.      DiaLogic.   Most of the information you will  need is held by the
  4477.      same DB() array used  when calling DiaLogic.   So, knowing  which
  4478.      options were selected is a simple  matter of accessing DB().  The
  4479.      other variables  which  are used  as  arguments in  the  call  to
  4480.      DiaLogic may also  be useful,  and the  information they  contain
  4481.      when  Action is  0  is summarized  below (further  discussion for
  4482.      other Actions is provided in Part VI: Advanced Topics):
  4483.  
  4484.        Variable Returned when Action% is 0
  4485.  
  4486.        DB()     For all DBEs (except the text box) information is
  4487.                 returned in DB(1, SequenceNo).Default.  The text
  4488.                 box uses both DB(1, SequenceNo).TextString (to
  4489.                 hold the input string) and DB(1,
  4490.                 SequenceNo).NumberOne (to hold the string
  4491.                 length).
  4492.        Action%  Remains 0.
  4493.        Focus%   Contains the DBE Sequence number on which the input
  4494.                 focus rested when the dialog box was closed.
  4495.        Ky$      Contains the keystroke used to close the dialog box.
  4496.  
  4497.  
  4498.      The first thing  we should determine once control  is returned to
  4499.      the calling program  is whether or not to process the dialog box.
  4500.      If the  user pressed  <Esc> or used  the <Cancel>  command button
  4501.      then  the information returned by  DiaLogic should be ignored and
  4502.      the  calling  program  should  continue  doing   something  else.
  4503.      However, if the user pressed <Enter> and <Cancel> was not  active
  4504.      then the  calling program should interpret and  possibly react to
  4505.      choices made.
  4506.  
  4507.      The Search dialog box presented earlier has a text box, two check
  4508.      boxes, and three command buttons and it is shown again  below for
  4509.      your  convenience.  You  may also feel  the need to  refer to the
  4510.      SEARCH.DB  template  in  order to  fully-appreciate  the  ensuing
  4511.      discussion.    This template  appears  in  Part III:  Creating  A
  4512.      Template.
  4513.  
  4514.  
  4515.                                                                     85
  4516.  
  4517.  
  4518.  
  4519.  
  4520.      DiaLogic
  4521.  
  4522.  
  4523.  
  4524.                                    Search                        
  4525.                                                                  
  4526.             Find What:                                           
  4527.                                                                  
  4528.                                                                  
  4529.             [ ] Match Upper/Lower Case                           
  4530.             [ ] Whole Word                                       
  4531.                                                                  
  4532.                                                                  
  4533.                  < OK >         < Cancel >        < Help >       
  4534.                                                                  
  4535.  
  4536.  
  4537.      In deciding not  to process the dialog  box we must  examine Ky$.
  4538.      If it  is equal  to CHR$(27),  ASCII for  <Esc>, then  either the
  4539.      <Esc> key was pressed or <Cancel> was  active when the dialog box
  4540.      was closed.   Recall that a dialog  box is closed when  a command
  4541.      button is ``pushed'', an Alt-key is used, or if the mouse is used
  4542.      to double-click on a list box  item.  If the <Cancel> button  was
  4543.      indeed pushed then we  may assume that the user wished to nullify
  4544.      selections made on the dialog box.
  4545.  
  4546.      If we discover that a cancel operation has not been  chosen, then
  4547.      we should process the dialog box by analyzing information entered
  4548.      by the user.
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.      86
  4565.  
  4566.  
  4567.  
  4568.  
  4569.                                                Generating a Dialog Box
  4570.  
  4571.      Command buttons are  usually the first DBEs to  be analyzed since
  4572.      they often direct what the calling program  is to do next.  We've
  4573.      already discussed what  should happen if <Cancel> is  chosen.  In
  4574.      our  SEARCH.DB example,  there  two additional  command  buttons:
  4575.      <OK>,  and  <Help>.   Since  DB().TextString for  command buttons
  4576.      specifies what should be returned in Ky$,  our SEARCH.DB template
  4577.      uses the following values:
  4578.  
  4579.  
  4580.  
  4581.  
  4582.        Command Button    DB().TextString    Meaning
  4583.  
  4584.           <OK>           CHR$(13)           <Enter>
  4585.           <Cancel>       CHR$(27)           <Esc>
  4586.           <Help>         CHR$(0) + CHR$(59) <F1>
  4587.  
  4588.  
  4589.  
  4590.      Thus, if <Help> is chosen or if <F1>  is pressed then Ky$ will be
  4591.      equivalent to CHR$(0) + CHR$(59).  Thus, DiaLogic will return the
  4592.      same value when either <Help> or <F1> is used.  
  4593.      An alternative  is to detect which  command button was  pushed by
  4594.      examining  DB().Default.  Only  one command button  will have its
  4595.      DB().Default value  set to -1: this  is the command  button which
  4596.      was pushed.  All other command buttons in the template will  have
  4597.      DB().Default equal to 0.  
  4598.  
  4599.      If <Help> was  pushed then we should print a help message.  After
  4600.      the  help message we  will want to display  the Search dialog box
  4601.      again.   (To stack  a  help message  dialog box  onto the  Search
  4602.      dialog box, please refer to Part VI: Advanced Topics.)
  4603.  
  4604.  
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.                                                                     87
  4614.  
  4615.  
  4616.  
  4617.  
  4618.      DiaLogic
  4619.  
  4620.      If <OK> is pushed  then we should  gather information about  what
  4621.      string  to find, and whether  the search should be case-sensitive
  4622.      or for  whole words  only.   The  search string  is available  in
  4623.      DB(1, 2).TextString and its length is held in DB(1, 2).NumberOne.
  4624.      The other information  needed is in DB(1, 3).Default,  which will
  4625.      be -1  if  Match  Upper/Lower  Case  is  checked,  and  in  DB(1,
  4626.      4).Default, which will be -1 if Whole Words is checked.
  4627.  
  4628.      We have offered a decision-making process which looks like this:
  4629.  
  4630.  
  4631.  
  4632.              .
  4633.              .
  4634.              .
  4635.  
  4636.        If not <Cancel> then
  4637.           If <Help> then
  4638.              Print help message
  4639.              Generate Search dialog box again
  4640.           End if
  4641.           If <OK> then
  4642.              Get the search string
  4643.              Get the case-matching requirement
  4644.              Get the whole-words only requirement
  4645.           End if
  4646.        End if
  4647.              .
  4648.              .
  4649.              .
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.      88
  4663.  
  4664.  
  4665.  
  4666.  
  4667.                                                Generating a Dialog Box
  4668.  
  4669.      Of course,  you may use whatever logic  is best for you.   We are
  4670.      presenting this method as one possible approach.
  4671.  
  4672.      Our final program,  listed below, will generate a  dialog box and
  4673.      then processs it:  
  4674.  
  4675.  
  4676.        DEF INT A-Z                    'make variables integer
  4677.        '$INCLUDE: 'DIALOGIC.BI'       'include TYPE definitions
  4678.        '$DYNAMIC                      'make arrays dynamic
  4679.        REDIM DB(2, 30) AS DialogType  'dimension DB()
  4680.        REDIM LB(0) AS ListType        'dimension LB()
  4681.        Level% = 1                     'set the Level
  4682.        '$INCLUDE: 'SEARCH.DB'         'include  the   dialog  box     
  4683.                                       'template
  4684.        Action% = 0                    'use Action 0
  4685.        Focus% = 0                     'set Focus
  4686.                                       'make the call
  4687.        CALL DiaLogic(DB(), LB(), Action%, Focus%, Ky$)
  4688.        IF Ky$ <> CHR$(27) THEN        'check for <Esc> or <Cancel>
  4689.           IF Ky$ = CHR$(0) + CHR$(59) THEN  'check for <F1> or <Help>
  4690.              LOCATE 1,1               'locate cursor
  4691.              PRINT "You pressed <Help>." 'print a message
  4692.           END IF
  4693.           IF Ky$ = CHR$(13) THEN      'check for <Enter> or <OK>
  4694.                                       'get the search string
  4695.              Search$ = RTRIM$(DB(Level%, 2).TextString
  4696.                                       'get right-side spaces
  4697.              Search$  =  Search$  + SPACE$(DB(Level%,  2).NumberOne  -
  4698.                 LEN(Search$))
  4699.                                       'get Upper/Lower Case
  4700.              ULCase = DB(Level%, 3).Default
  4701.                                       'get Whole Words
  4702.              WWords = DB(Level%, 4).Default
  4703.           END IF
  4704.        END IF
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.                                                                     89
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.                                   DiaLogic
  4729.  
  4730.  
  4731.                                   PART IV
  4732.                         CREATING STANDALONE PROGRAMS
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.      DiaLogic
  4740.  
  4741.      Compiling DiaLogic
  4742.  
  4743.      Since DiaLogic is  supplied to you  as a BASIC  module, you  will
  4744.      need  to create a DiaLogic  object file which  then can be linked
  4745.      with  programs  that   make  calls  to  it.     You  can  compile
  4746.      DIALOGIC.BAS from the command line as follows:
  4747.  
  4748.        BC DIALOGIC /O;
  4749.  
  4750.      This  will create  DIALOGIC.OBJ.   You  should also  compile your
  4751.      programs which call DiaLogic using this syntax:
  4752.  
  4753.        BC BASICPROGRAM /O;
  4754.  
  4755.      You will need to compile all your own modules separately.
  4756.  
  4757.  
  4758.        Note:
  4759.           If you plan  to use  huge arrays, DiaLogic is  prepared:
  4760.           the  DB()  and LB()  TYPE  definitions  have  structures
  4761.           which are a power-of-two in length.  Be sure  to specify
  4762.           the /AH command line switch when compiling.
  4763.  
  4764.  
  4765.  
  4766.      Linking with DiaLogic
  4767.  
  4768.      Once you have compiled  all your programs to .OBJ files, you will
  4769.      need to create a final stand-alone .EXE file before it can be run
  4770.      from DOS.    Keep in  mind that  because  DiaLogic uses  external
  4771.      assembler routines you will need to specify its assembler library
  4772.      file, DIALOGIC.LIB, when linking.
  4773.  
  4774.      If you are compiling and linking manually from DOS then you would
  4775.      specify  all  your  BASIC-compiled  object  modules,  along  with
  4776.      DIALOGIC.LIB, like this:
  4777.  
  4778.        LINK BASICPROGRAM+DIALOGIC.OBJ,,NUL,DIALOGIC.LIB
  4779.  
  4780.  
  4781.  
  4782.  
  4783.      94
  4784.  
  4785.  
  4786.  
  4787.  
  4788.                                           Creating Standalone Programs
  4789.  
  4790.      If you prefer you can start LINK without any options and wait for
  4791.      it to prompt you for the  information it needs.  To do this  just
  4792.      type:
  4793.  
  4794.        LINK
  4795.  
  4796.      You may also  specify more than  one library  when linking.   For
  4797.      example, if you need assembler routines from both DiaLogic and  a
  4798.      library  file called PRO.LIB,  you may tell  LINK to use  both of
  4799.      them:
  4800.  
  4801.        LINK BASICPROGRAM+DIALOGIC.OBJ,,NUL,DIALOGIC PRO
  4802.  
  4803.      You may also add single object modules at LINK time, even if they
  4804.      are not present in a library at all:
  4805.  
  4806.        LINK BASICPROGRAM+DIALOGIC.OBJ+OBJECT,,NUL,DIALOGIC PRO
  4807.  
  4808.      If you  do wish to  combine several libraries into  a single .LIB
  4809.      file, that is quite easy too.   Though the LIB library manager is
  4810.      usually employed to add  or remove object  modules, you may  also
  4811.      add one or more complete libraries like this:
  4812.  
  4813.        LIB LIBRARY1.LIB+LIBRARY2.LIB+LIBRARY3.LIB
  4814.  
  4815.      One useful LINK option you should be  aware of is the /EX command
  4816.      line switch.  When LINK is  invoked with /EX, it creates an  .EXE
  4817.      file in  a special  ``packed'' format.   Not  unlike the  various
  4818.      archive programs,  the code  and data are  compressed to  take up
  4819.      less disk space.   When the program  is run, the first  code that
  4820.      actually executes is  an unpacking  routine that puts  everything
  4821.      back together again.  The /EX switch is specified like this:
  4822.  
  4823.        LINK BASICPROGRAM+DIALOGIC.OBJ,,NUL,DIALOGIC.LIB /EX
  4824.  
  4825.      A packed  program will  require less  disk space,  however it  of
  4826.      course requires the same amount of memory when it is run.
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.                                                                     95
  4833.  
  4834.  
  4835.  
  4836.  
  4837.      DiaLogic
  4838.  
  4839.      Adding to the DIALOGIC Quick Library
  4840.  
  4841.      We have provided you with the needed Quick Library file  to allow
  4842.      operation  of DIALOGIC.BAS when  in the environment.   This Quick
  4843.      Library  contains  the  assembler   routines  on  which  DiaLogic
  4844.      depends.   However, you may  need to  add other routines  so that
  4845.      they  too  are available  in  the  QuickBASIC environment.    For
  4846.      example, you may need to combine assembler or BASIC routines from
  4847.      QuickPak Professional with DIALOGIC.QLB.
  4848.  
  4849.      Quick Libraries are created with the version of LINK current with
  4850.      or subsequent to the release of QuickBASIC version 4.   Microsoft
  4851.      has documented many of the capabilities of LINK in the QuickBASIC
  4852.      manuals, though there  are additional useful features  with which
  4853.      you should become familiar.
  4854.  
  4855.      Normally, LINK  expects  a  list  of  object  file  names  to  be
  4856.      specified for inclusion in  the Quick Library  being built.   But
  4857.      you  may also combine one or  more entire .LIB libraries as well.
  4858.      (A .LIB file simply contains one or more .OBJ modules in a single
  4859.      file.)   This  feature is  particularly  useful if  you  need  to
  4860.      combine several .LIB library files into a single Quick Library.
  4861.  
  4862.      To create a new Quick Library  comprised of one or more .LIB  and
  4863.      .OBJ files, invoke LINK like this:
  4864.  
  4865.        LINK /Q LIBFILE1.LIB LIBFILE2.LIB OBJ1 OBJ2,LIBNAME,NUL,BQLB45
  4866.  
  4867.      The /Q option  tells LINK that  it is to  create a Quick  Library
  4868.      rather than an .EXE file.  LIBFILE1.LIB and LIBFILE2.LIB are  the
  4869.      library files being incorporated into the new  Quick Library, and
  4870.      OBJ1 and OBJ2  are object modules.   Of course,  you can mix  and
  4871.      match library and object files in any order you would like.
  4872.  
  4873.      The .LIB extension  is very  important, because  without it  LINK
  4874.      would be  looking for files with an  .OBJ extension.  Notice that
  4875.      an extension is not needed for the object files.
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.      96
  4882.  
  4883.  
  4884.  
  4885.  
  4886.                                           Creating Standalone Programs
  4887.  
  4888.      The LIBNAME parameter  is the name that  you want to use  for the
  4889.      new Quick Library  being built.   Without the LIBNAME  parameter,
  4890.      LINK will default to the same name as the first .LIB or .OBJ file
  4891.      in the list.  In the example above, the file generated would have
  4892.      been named the same as LIBFILE1.LIB if LIBNAME had been  omitted.
  4893.      In  that case,  though,  the  comma  ``place  holder''  is  still
  4894.      required:
  4895.  
  4896.        LINK /Q LIBNAME1.LIB LIBNAME2.LIB OBJ1 OBJ2,,NUL,BQLB45
  4897.  
  4898.      The NUL parameter prevents LINK from generating a list file,  and
  4899.      BQLB45.LIB  is  a  special   library  supplied  with  QuickBASIC.
  4900.      BQLB45.LIB, for example, has nothing to do  with Dialog Software,
  4901.      and is required  for making any  Quick Library that will  be used
  4902.      with BASIC.  Note that BQLB45 may have a slightly different name,
  4903.      depending on the version of QuickBASIC.
  4904.  
  4905.      One final important note about making Quick Libraries is the /SEG
  4906.      option.   When many  separate object modules  are being combined,
  4907.      the number  of  code and  data  segments may  exceed  the  LINK's
  4908.      default maximum of 128.  When we create Quick Libraries we always
  4909.      tell LINK to allow for up to 256 segments like this:
  4910.  
  4911.        LINK /Q /SEG:256 LIBFILE.LIB,,NUL,BQLB45
  4912.  
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.                                                                     97
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.                                   DiaLogic
  4946.  
  4947.  
  4948.                                   PART VI
  4949.                               ADVANCED TOPICS
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.                                                        Advanced Topics
  4957.  
  4958.      Creating  advanced  dialog  boxes  is  a  matter  of  being  more
  4959.      acquainted with the  use of the Action% argument  in the DiaLogic
  4960.      call.  While most advanced uses of dialog boxes, such as stacking
  4961.      and  multi-tasking,  are  presented  in  the  commented  DEMO.BAS
  4962.      program, you may  find the following explanations  and additional
  4963.      examples to be  very helpful.  You should understand  that due to
  4964.      the power and flexibility of  DiaLogic, the examples which follow
  4965.      are by no means exhaustive, nor do they represent a ``best way''.
  4966.      You will benefit most by carefully studying our  example programs
  4967.      for a conceptual  understanding, and  by reading the  discussions
  4968.      below.  After doing  this the best teacher will be the experience
  4969.      you gain by experimenting on your own.
  4970.  
  4971.      This chapter consists of four sections.  In the first  section we
  4972.      will offer some  guidance on how to choose the type of dialog box
  4973.      you may need to generate.  In the second section we  will discuss
  4974.      single-tasking dialog boxes only, beginning with  a review of the
  4975.      simplest (i.e., Action-0) dialog box similar to the one presented
  4976.      in  Part IV: Generating  a Dialog Box.   In the  third section we
  4977.      will discuss multi-tasking dialog boxes which, by definition, are
  4978.      called in a polled mode.  And last, in the fourth section we will
  4979.      discuss ways to stack dialog boxes on top of one another.
  4980.  
  4981.  
  4982.        Note:
  4983.           In this section, we introduce Action values  as they are
  4984.           needed.   For  an overview of all  Action% values please
  4985.           refer to page 82.
  4986.  
  4987.  
  4988.  
  4989.      All  examples  in  this  section  use the  fully-commented  BASIC
  4990.      programs on the distribution diskette  which begin with the  word
  4991.      ``EXAMPLE''  and have  an appended number  to designate  to which
  4992.      example it corresponds.   Thus, EXAMPLE1.BAS contains  the sample
  4993.      program for  our first  discussion below.   Please  note that  in
  4994.      order to load  the example files  properly, QuickBASIC should  be
  4995.      started using  the DiaLogic Quick  Library which appears  on your
  4996.      distribution diskette.   Further, all  programs should be  loaded
  4997.      using the QuickBASIC File Open pull-down menu option.
  4998.  
  4999.  
  5000.                                                                    101
  5001.  
  5002.  
  5003.  
  5004.  
  5005.      DiaLogic
  5006.  
  5007.      This section uses two  dialog box templates:   FIND.DB, which  is
  5008.      exactly like the dialog  box used by  QuickBASIC 4.5, and a  help
  5009.      dialog  box  called   FINDH.DB.     Since  these  templates   are
  5010.      conceptually similar to the ones you created in Part IV: Creating
  5011.      a Template, this section makes an attempt to resume and  complete
  5012.      our previous discussions.
  5013.  
  5014.  
  5015.      Choosing a Dialog Box Type
  5016.  
  5017.      In general you  should use single-tasking dialog boxes since they
  5018.      are easiest  to implement and  are slightly faster  since polling
  5019.      does not occur.   Multi-tasking dialog boxes should  be used only
  5020.      when a background process must execute while the dialog box is in
  5021.      use.    Examples  of  necessary  background  processes  might  be
  5022.      updating the time on the screen or capturing input from a modem.
  5023.  
  5024.      If you  choose a single-tasking  dialog box  you should  consider
  5025.      whether you will need to stack dialog boxes.  Generally,  stacked
  5026.      dialog  boxes are used  only when a  dialog box requests  help or
  5027.      generates an error.  Still,  the choice to stack dialog  boxes is
  5028.      based more  on  aesthetics than  anything  else.   Since  stacked
  5029.      dialog boxes appear to  be on top of one another  (please see the
  5030.      discussion  about Level  on page  78),  it makes  sense that  the
  5031.      topmost dialog box should convey information about the dialog box
  5032.      directly beneath it.   Indeed, the convention  is to generate  an
  5033.      overlaying dialog only when the new dialog box will be presenting
  5034.      information related to the dialog box which generated it.
  5035.  
  5036.      If you  choose to  generate a multi-tasking  dialog box  then you
  5037.      have the  added ability to modify a dialog  box while it is being
  5038.      used.   This feature is useful  when certain options  on a dialog
  5039.      box must be immediately updated based on selections made.  Multi-
  5040.      tasking  dialog  boxes  are  polled  from  the  calling  program,
  5041.      therefore, any information  entered by the  user may be  examined
  5042.      after each polling cycle. 
  5043.  
  5044.      Please carefully review all of our examples.  Once you understand
  5045.      the various uses of  Action, you will  realize that DiaLogic  can
  5046.      support any kind of dialog box you will need to implement.
  5047.  
  5048.  
  5049.      102
  5050.  
  5051.  
  5052.  
  5053.  
  5054.                                                        Advanced Topics
  5055.  
  5056.      Single-Tasking Dialog Boxes
  5057.  
  5058.      As we mentioned earlier, single-tasking dialog boxes require that
  5059.      full  control be passed to  DiaLogic while a  dialog box is being
  5060.      used.
  5061.  
  5062.      Action   0  provides   the  most   straightforward  "no-nonsense"
  5063.      interface to  DiaLogic.  In  fact, when Action  is 0  the program
  5064.      control will remain with DiaLogic until the dialog box is  closed
  5065.      by the user.   At that point the  dialog box will be removed  and
  5066.      the screen will be restored to its pre-dialog box state.
  5067.  
  5068.      The  use  of  Action  0 also  will  not  inhibit  the  ability to
  5069.      effectively communicate with  the user.   In fact, once  DiaLogic
  5070.      removes a  dialog box  it is  prepared to  generate another  one.
  5071.      This makes it possible to immediately follow one dialog box  with
  5072.      another.   Our first example program,  EXAMPLE1.BAS, demonstrates
  5073.      this.   The user is  presented with a  Find dialog  box.  If  the
  5074.      <Help> command  button is  used, then the  dialog box  is removed
  5075.      from the screen and control is passed back to the calling program
  5076.      (EXAMPLE1.BAS, in  this instance).   After,  the calling  program
  5077.      will generate a new dialog box which displays a help message in a
  5078.      list box.  When the user closes this dialog box (by pushing <OK>)
  5079.      the calling  program will  again generate  the  Find dialog  box.
  5080.      This cycle occurs in a DO loop and can continue each  time <Help>
  5081.      is pushed.   Remember  that since all  Action-0 dialog  boxes are
  5082.      generated  at Level  1 there  is little  memory that needs  to be
  5083.      dedicated to  the DB() array.   When <OK> or <Cancel>  is finally
  5084.      chosen the calling program may then resume processing.
  5085.  
  5086.      EXAMPLE1.BAS demonstrates how an Action-0 dialog box can preserve
  5087.      its settings.   In  this instance,  the user may  have entered  a
  5088.      search string before  feeling the need to request  help.  Suppose
  5089.      that this search string was a complex formula, and required  much
  5090.      careful typing.  It would be very  unfair to the user if DiaLogic
  5091.      cleared the string  whenever a simple request for  help was made.
  5092.      An elegant  way  to use  Action-0  dialog boxes  is  to  preserve
  5093.      selected  values  for  later,  so   that  preferred  options  are
  5094.      automatically selected for  the user when the dialog  box is next
  5095.      generated. 
  5096.  
  5097.  
  5098.                                                                    103
  5099.  
  5100.  
  5101.  
  5102.  
  5103.      DiaLogic
  5104.  
  5105.      One technique  for preserving  dialog box settings  makes use  of
  5106.      variable names  in the  dialog box template.   For  instance, the
  5107.      Find What text box template definition appears like this:
  5108.  
  5109.        DB(Level%, 2).Code = 2
  5110.        DB(Level%, 2).Y = 2
  5111.        DB(Level%, 2).X = 14
  5112.        DB(Level%, 2).Wdth = 44
  5113.        DB(Level%, 2).BorderType = 1
  5114.        DB(Level%, 2).PrimaryColor = 112
  5115.        DB(Level%, 2).WindowColor = 112
  5116.        DB(Level%, 2).SelectedColor = 7
  5117.        DB(Level%, 2).TextY = 3
  5118.        DB(Level%, 2).TextX = 3
  5119.        DB(Level%, 2).Text = "~Find What:"
  5120.        DB(Level%, 2).TextColor = 112
  5121.        DB(Level%, 2).KeyColor = 127
  5122.        DB(Level%, 2).TextString = Search$
  5123.        DB(Level%, 2).ItemLength = 50
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.  
  5147.      104
  5148.  
  5149.  
  5150.  
  5151.  
  5152.                                                        Advanced Topics
  5153.  
  5154.      Notice that the default edit string is assigned to Search$ in the
  5155.      template!    An include  file  may contain  variable  names since
  5156.      QuickBASIC  compiles  it along  with  the  rest of  the  program.
  5157.      EXAMPLE1.BAS preserves all the Find dialog box selections as soon
  5158.      as it returns from the call using the following statements:
  5159.  
  5160.  
  5161.  
  5162.              .
  5163.              .
  5164.              .
  5165.                                'Search$ holds our
  5166.                                '   search string
  5167.            Search$ = MID$(DB(Level%, 2).TextString, 1, _
  5168.                DB(Level%, 2).NumberOne)
  5169.            MatchCase = DB(Level%, 3).Default
  5170.                    '-1 if Match Case is checked
  5171.            WholeWord = DB(Level%, 4).Default
  5172.                    '-1 if Whole Words is checked
  5173.            SearchType = DB(Level%, 5).Default
  5174.                    '1 for Active Window, 2 for 
  5175.                    '   Current Module,  or 3
  5176.                    '   for All Modules
  5177.  
  5178.  
  5179.  
  5180.      Each   variable  (i.e.,   Search$,   MatchCase,  WholeWord,   and
  5181.      SearchType) appears  in the  default assignments  of the  FIND.DB
  5182.      dialog box template.  
  5183.  
  5184.  
  5185.  
  5186.  
  5187.  
  5188.  
  5189.  
  5190.  
  5191.  
  5192.  
  5193.  
  5194.  
  5195.  
  5196.                                                                    105
  5197.  
  5198.  
  5199.  
  5200.  
  5201.      DiaLogic
  5202.  
  5203.      Another useful  technique  is  to  use  variable  names  for  the
  5204.      command-button key.  Consider the  <Help> command button template
  5205.      structure for the Find dialog box used by EXAMPLE1.BAS:
  5206.  
  5207.        DB(Level%, 11).Code = 7
  5208.        DB(Level%, 11).Y = 11
  5209.        DB(Level%, 11).X = 43
  5210.        DB(Level%, 11).Text = "~Help"
  5211.        DB(Level%, 11).PrimaryColor = 112
  5212.        DB(Level%, 11).WindowColor = 112
  5213.        DB(Level%, 11).SelectedColor = 7
  5214.        DB(Level%, 11).KeyColor = 127
  5215.        DB(Level%, 11).SecondaryColor = 127
  5216.        DB(Level%, 11).TextString = Help$
  5217.  
  5218.  
  5219.      Recall that the string assigned to  DB().TextString for a command
  5220.      button is returned in Ky$ whenever that command button is pushed.
  5221.      Thus, if the <Help> is active when the dialog box is closed, then
  5222.      Ky$ will have the string value of  Help$.  This is possible since
  5223.      the very beginning  of EXAMPLE1.BAS (before the  template include
  5224.      statements) defines several variables as such:
  5225.  
  5226.         Esc$ = CHR$(27)                        
  5227.         Help$ = CHR$(0) + CHR$(59)    
  5228.         OK$ = CHR$(13)
  5229.  
  5230.      The Help$ has  the same string value as the <F1> key; ESC$ is the
  5231.      same as <Esc>; and OK$ is the same as <Enter>.
  5232.  
  5233.      Knowing which command button  was active will  let us know if  we
  5234.      should ignore the dialog box (<Cancel>), generate a help  message
  5235.      (<Help>)  or  accept  the  dialog  box information  and  continue
  5236.      processing (<OK>).  This decision process occurs in a SELECT CASE
  5237.      statement.
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.      106
  5246.  
  5247.  
  5248.  
  5249.  
  5250.                                                        Advanced Topics
  5251.  
  5252.      Multi-Tasking Dialog Boxes
  5253.  
  5254.      Multi-tasking dialog  boxes have the  ability to be  behave quite
  5255.      normally even though they are being repeatedly called in a  loop.
  5256.      These dialog  boxes are  called  initially with  an Action  of 1,
  5257.      which displays a  dialog box and returns to  the calling program.
  5258.      Subsequent  calls  are made  using an  Action of  3.   The Action
  5259.      remains 3  until input is  received by the  dialog box,  at which
  5260.      point the Action  becomes 4.  This allows  the calling program to
  5261.      react to  the dialog box only  when some dialog  box activity has
  5262.      occurred.  This creates an efficient polling structure.
  5263.  
  5264.  
  5265.        Note:
  5266.           If the calling  program wishes  to terminate  the polling
  5267.           mode, then Action may  be set  to 7, and  the dialog  box
  5268.           will resume execution in single-tasking mode as if it had
  5269.           been generated with an Action of 6.  Once the  dialog box
  5270.           is closed it must be removed from the screen using Action
  5271.           5.  Action 6 is discussed below.
  5272.  
  5273.  
  5274.      EXAMPLE2.BAS provides  a demonstration of  a multi-tasking dialog
  5275.      box.  This program  updates the time on the dialog  box at a rate
  5276.      which is fast enough to appear  smooth.  The dialog box is  fully
  5277.      able to accept input, both  with the mouse or with  the keyboard,
  5278.      even though it  is being polled.   The core of the  polling takes
  5279.      place in a nested DO loop.
  5280.  
  5281.      The innermost  DO loop  will keep  calling DiaLogic until  Action
  5282.      becomes 4.  Recall that  Action 3 allows DiaLogic to  return to a
  5283.      calling program  as soon  as it checks  for input.   If  input is
  5284.      received, DiaLogic sets Action to 4.  Action 4 is simply a signal
  5285.      for the calling program that some input (either from the keyboard
  5286.      or mouse) was received by DiaLogic.
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.                                                                    107
  5294.  
  5295.  
  5296.  
  5297.  
  5298.      DiaLogic
  5299.  
  5300.      Once Action  is 4,  the calling  program should  first check  the
  5301.      command buttons  in  order to  determine  what to  do next.    In
  5302.      EXAMPLE2.BAS  we  have  provided some  interesting  ideas  on how
  5303.      multi-tasking dialog boxes may be used.
  5304.  
  5305.      One aesthetic consideration of multi-tasking  dialog boxes is the
  5306.      cursor.  The blinking hardware  cursor will appear to ``flicker''
  5307.      or ``dart around''  during some background  processes.  For  this
  5308.      reason,  we suggest turning the cursor  off before the background
  5309.      process like this:
  5310.  
  5311.        LOCATE , , 0
  5312.  
  5313.      The cursor may be turned on again by this statement:
  5314.  
  5315.        LOCATE , , 1
  5316.  
  5317.  
  5318.  
  5319.        Note:
  5320.           Although this example shows  that the time (or any  other
  5321.           process) can be run alternately with DiaLogic, you should
  5322.           be aware that  a dialog box  can be polled  without doing
  5323.           any background task.  Thus, our time-update routine could
  5324.           just as  well  be  a  series  of  REM  statements.    The
  5325.           important point here is that using a dialog box in polled
  5326.           mode offers a calling  program the ability to dynamically
  5327.           interact   with  a  dialog  box,   effectively  extending
  5328.           DiaLogic's processing.
  5329.  
  5330.  
  5331.  
  5332.      The <Help> command button in EXAMPLE2.BAS is displayed in blue to
  5333.      make it  different from other command  buttons.  While  any color
  5334.      will  do,  we  have  made <Help>  different  because  no  help is
  5335.      available for  this dialog box.   If <Help> is  selected, then an
  5336.      error beep will be sounded, and the choice will be ignored.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.      108
  5343.  
  5344.  
  5345.  
  5346.  
  5347.                                                        Advanced Topics
  5348.  
  5349.      While  deactivating command button may not be something you would
  5350.      wish  to do,  the technique  alone demonstrates  how  the calling
  5351.      program can  participate in  the logic  involved when  processing
  5352.      user input.
  5353.  
  5354.      The <OK> command  button demonstrates how to update  a dialog box
  5355.      on-the-fly, that is, while it is being used.  Thus, whenever <OK>
  5356.      is selected,  a special  message appears  in the  text box,  both
  5357.      check boxes are  checked, and choice 2 in the Search group box is
  5358.      selected.  This happens  very quickly, and  after the dialog  box
  5359.      remains  fully-functional.    This  feature  allows  the  calling
  5360.      program to insure  that certain options are  checked or unchecked
  5361.      based  on what has  been selected.   Although EXAMPLE2.BAS checks
  5362.      for which command button was pushed, it could have examined which
  5363.      check box was  selected before deciding to update  the dialog box
  5364.      elements.   Your own experimentation  will surely result  in even
  5365.      more creative ways to implement multi-tasking dialog boxes.
  5366.  
  5367.  
  5368.      Stacked Dialog Boxes
  5369.  
  5370.      Overview
  5371.  
  5372.      The benefits to stacked dialog boxes are mainly aesthetics and  a
  5373.      desire to create a  superior user interface.   Our discussion  of
  5374.      stacked dialog  boxes will  use the  term primary  dialog box  to
  5375.      refer to the first  dialog box that  is generated, and  secondary
  5376.      dialog box to refer to the overlaying dialog box.  
  5377.  
  5378.  
  5379.        Note:
  5380.           Although this section will focus on the use of two dialog
  5381.           boxes only, DiaLogic can of course handle as  many dialog
  5382.           boxes  as  you  wish.    However, some  variables  in the
  5383.           DiaLogic source  program, DIALOGIC.BAS, will  have to  be
  5384.           modified if  you desire  to stack  more  than two  dialog
  5385.           boxes  on  the screen.    If  this  applies,  please  see
  5386.           Appendix B: Modifying DIALOGIC.BAS.
  5387.  
  5388.  
  5389.  
  5390.  
  5391.                                                                    109
  5392.  
  5393.  
  5394.  
  5395.  
  5396.      DiaLogic
  5397.  
  5398.      In order  to stack dialog  boxes the  primary dialog box  must be
  5399.      generated in such a  way that control will be passed  back to the
  5400.      calling program before the dialog box is removed from the  screen
  5401.      and before the  decision to generate an overlaying  dialog box is
  5402.      made.  In order to accomplish  this, the primary dialog box  must
  5403.      be generated  using an Action  of 1 or  6.  Recall that  Action 1
  5404.      generates a  dialog box  and returns  immediately to  the calling
  5405.      program.  Action 6, on the other hand, generates a dialog box and
  5406.      waits for input, then  it returns to  the calling program.   Both
  5407.      Action 1 and Action 6 will keep the dialog box on the screen when
  5408.      returning to the calling program.
  5409.  
  5410.      The secondary dialog  box is most often generated  with an Action
  5411.      of  0 simply  because it is  very rare  and often  undesirable to
  5412.      stack  more than 2 dialog  boxes.  However, if you wish to  stack
  5413.      dialog boxes to a Level greater than 2 then you may  generate the
  5414.      secondary  dialog  box just  like  the primary  dialog  box using
  5415.      Actions 1 and 6 (please see the Note on the preceding page). 
  5416.  
  5417.      Once the  secondary dialog  box is  removed from  the screen  the
  5418.      underlying primary dialog box  has to be  re-activated.  This  is
  5419.      easily accomplished with a single  call to DiaLogic using  Action
  5420.      2, which will  re-read the DB() array and update  all text boxes,
  5421.      list boxes,  check boxes, and option buttons in the highest-Level
  5422.      dialog box currently on the screen.  After this, DiaLogic must be
  5423.      called with Action 7 in order for DiaLogic to resume  processing.
  5424.      Action 7 behaves just like Action 6, and full control will remain
  5425.      with DiaLogic until the dialog box is closed.  At this point, the
  5426.      dialog box  remains on  the screen, and  the calling  program can
  5427.      decide what to do next.  Like Action-1 and Action-6 dialog boxes,
  5428.      when  a  dialog box  is  re-activated  using  Action 7,  it  must
  5429.      ultimately be  removed from  the screen with  a call  to DiaLogic
  5430.      using an Action of 5.  
  5431.  
  5432.      We will present two programs.  The first, EXAMPLE3.BAS, discusses
  5433.      how  to  stack   single-tasking  dialog   boxes.    The   second,
  5434.      EXAMPLE4.BAS, discusses how to stack multi-tasking dialog boxes.
  5435.  
  5436.  
  5437.  
  5438.  
  5439.  
  5440.      110
  5441.  
  5442.  
  5443.  
  5444.  
  5445.                                                        Advanced Topics
  5446.  
  5447.      Single-Tasking Stacked Dialog Boxes
  5448.  
  5449.      EXAMPLE3.BAS shows  a Find  dialog box  which is  generated using
  5450.      Action 6.  This Action displays a dialog box and waits for input.
  5451.      There  are three  command buttons  on  it:   <OK>, <Cancel>,  and
  5452.      <Help>.  If  <OK> is pushed, the  dialog box is removed  from the
  5453.      screen using Action 5 and is processed  normally.  If <Cancel> is
  5454.      pushed, then  the dialog  box is  removed from  the screen,  also
  5455.      using Action  5, and  the dialog box  contents are  ignored.   If
  5456.      <Help> is  pushed then the Find dialog box remains on the screen.
  5457.      At this point the calling program sets Level to 2 and defines the
  5458.      secondary dialog box template.  Then, DiaLogic is called with  an
  5459.      Action of  0.   This  will  generate a  help  dialog box  as  the
  5460.      secondary dialog box.   When the Help dialog  box is acknowledged
  5461.      then it will be removed from the screen.  In order to re-activate
  5462.      the primary  Find dialog  box, DiaLogic  must be  called with  an
  5463.      Action of 2 followed  by an Action of 7.  The  Find dialog box is
  5464.      ultimately removed from the screen using Action 5.
  5465.  
  5466.      Thus, to stack  single-tasking dialog boxes, the primary one must
  5467.      be generated with an Action of 6, which is identical to an Action
  5468.      of 0 except the dialog box is not removed from the screen when it
  5469.      is closed.   Action 6 therefore allows DiaLogic to  return to the
  5470.      calling program while leaving  a full dialog  box on the  screen.
  5471.      When the time  comes to remove  the dialog box, DiaLogic  must be
  5472.      called  with an  Action of 5.    This Action  always removes  the
  5473.      dialog box with the highest Level from the screen.
  5474.  
  5475.  
  5476.  
  5477.        Note:
  5478.           Never remove a dialog  box from the screen by using  the
  5479.           CLS   (clear  screen)  BASIC  statement,  or  any  other
  5480.           method.  Avoiding the  use of Action 5 in  this way will
  5481.           cause DiaLogic's internal pointers to be corrupted.
  5482.  
  5483.  
  5484.  
  5485.  
  5486.  
  5487.  
  5488.  
  5489.                                                                    111
  5490.  
  5491.  
  5492.  
  5493.  
  5494.      DiaLogic
  5495.  
  5496.      Notice that in this example our  program does not bother to check
  5497.      anything  about  the dialog  box if  Action  is not  4.   This is
  5498.      efficient, since  no background time  is wasted: this  allows the
  5499.      greatest  portion  of  the  computer  time  to  be  dedicated  to
  5500.      DiaLogic's processing.
  5501.  
  5502.  
  5503.      Multi-Tasking Stacked Dialog Boxes
  5504.  
  5505.      EXAMPLE4.BAS shows  a Find  dialog box which  is generated  using
  5506.      Action 1.   This  Action displays  a dialog  box and  immediately
  5507.      returns to  the  calling program.    At this  point  the  calling
  5508.      program  can do anything  it wishes before  activating the dialog
  5509.      box.    One useful  idea  is to  print  information, such  as the
  5510.      current date, directly on the dialog box using a PRINT statement.
  5511.      In other words,  generating a dialog box with Action 1 allows the
  5512.      calling  program  to embellish  the  dialog box  with information
  5513.      which is not defined in the template.
  5514.  
  5515.      In EXAMPLE4.BAS, however,  the Action is set  to 3 and a  DO loop
  5516.      begins to  execute.  Since Action  is three the  call to DiaLogic
  5517.      will return after  the dialog box has  been polled.  The  time is
  5518.      printed  on the  dialog box to  demonstrate multi-tasking.   Then
  5519.      EXAMPLE4.BAS  checks to see  if Action is 4.   Recall that Action
  5520.      becomes  4 only  when the  dialog  box has  received some  input.
  5521.      While Action remains 3 the IF  statements are completely ignored.
  5522.      As soon as  Action becomes 4 the calling program checks to see if
  5523.      a command button  has been pushed.  If <Help>  is requested, then
  5524.      the Help dialog box is generated by setting Level% to 2, defining
  5525.      the template,  and calling DiaLogic  with an Action of  0.  Thus,
  5526.      the Help  dialog  box will  be  single-tasking, and  will  remove
  5527.      itself from the primary Find dialog box  as soon as it is closed.
  5528.      Once Help is acknowledged,   the primary Find  dialog box is  re-
  5529.      activated by calling DiaLogic with an  Action of 2 followed by an
  5530.      Action of 3, since we wish to continue multi-tasking.
  5531.  
  5532.      If <OK>  is pushed, then the Find dialog  box is removed from the
  5533.      screen using Action  5, and the results are printed.  If <Cancel>
  5534.      is pushed  then the  dialog box  is removed  but the  results are
  5535.      ignored.
  5536.  
  5537.  
  5538.      112
  5539.  
  5540.  
  5541.  
  5542.  
  5543.                                                        Advanced Topics
  5544.  
  5545.      It should be  clear that using Action the correct  way will allow
  5546.      many variations in  the way DiaLogic  is used.   We wish to  make
  5547.      this product  smaller, better,  and more  powerful with  each new
  5548.      release.   If you have ideas for improvement, both in the program
  5549.      or documentation, please let us know!  
  5550.  
  5551.      We hope you enjoy using DiaLogic.
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.  
  5573.  
  5574.  
  5575.  
  5576.  
  5577.  
  5578.  
  5579.  
  5580.  
  5581.  
  5582.  
  5583.  
  5584.  
  5585.  
  5586.  
  5587.                                                                    113
  5588.  
  5589.  
  5590.  
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.                                        DiaLogic
  5605.  
  5606.  
  5607.                                       APPENDICES
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.  
  5615.  
  5616.  
  5617.  
  5618.  
  5619.  
  5620.  
  5621.  
  5622.                                        DiaLogic
  5623.  
  5624.  
  5625.                                       APPENDIX A
  5626.                                  DIALOG BOX ELEMENTS
  5627.  
  5628.  
  5629.  
  5630.  
  5631.  
  5632.  
  5633.                                             Appendix A: Dialog Box Elements
  5634.  
  5635.           The Window
  5636.  
  5637.  
  5638.           DB(Level, 1).Code = 1
  5639.             Code for window.
  5640.           DB(Level, 1).Y = 
  5641.             Y coordinate of upper-left corner.
  5642.           DB(Level, 1).X =
  5643.             X coordinate of upper-left corner.
  5644.           DB(Level, 1).Height =
  5645.             Height of window.
  5646.           DB(Level, 1).Wdth =
  5647.             Width of window.
  5648.           DB(Level, 1).BorderType =
  5649.             Border type.  If negative then window will  ``explode.''
  5650.           DB(Level, 1).PrimaryColor =
  5651.             Color of window border. If negative then the window will cast a
  5652.             shadow.
  5653.           DB(Level, 1).WindowColor =
  5654.             Color of window.   If negative then  a horizontal line will  be
  5655.             drawn near the bottom of the dialog box.
  5656.           DB(Level, 1).Text =
  5657.             Optional centered title of the window.
  5658.           DB(Level, 1).TextColor =
  5659.             Color of window title.
  5660.           DB(Level, 1).SecondaryColor =
  5661.             Color of optional bottom horizonal line.
  5662.           DB(Level, 1).NumberOne =
  5663.             Number of screen lines.   This number may be 25,  43, 50 or 60,
  5664.             depending on the type of display adapter used.  Default is 25.
  5665.  
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.                                                                       A - 3
  5678.  
  5679.  
  5680.  
  5681.  
  5682.           DiaLogic
  5683.  
  5684.           Text Box
  5685.  
  5686.           DB().Code = 2
  5687.             Code for text box.
  5688.           DB().Y = 
  5689.             Y coordinate of upper-left corner.
  5690.           DB().X =
  5691.             X coordinate of upper-left corner.
  5692.           DB().Wdth =
  5693.             Width of text box.
  5694.           DB().BorderType =
  5695.             Border type.
  5696.           DB().PrimaryColor =
  5697.             Border color.
  5698.           DB().WindowColor =
  5699.             Color of unselected text inside the text box window.
  5700.           DB().SelectedColor =
  5701.             Color of selected text.
  5702.           DB().TextY =
  5703.             Y coordinate for text box label.
  5704.           DB().TextX =
  5705.             X coordinate for text box label.
  5706.           DB().Text =
  5707.             Text box label.  May contain a tilde for Alt-key operation.
  5708.           DB().TextColor =
  5709.             Color of text box label.
  5710.           DB().KeyColor =
  5711.             Color of the Alt-key in the text box label.
  5712.           DB().TextString =
  5713.             Text box default edit string.
  5714.           DB().ItemLength =
  5715.             Maximum number of characters which may be entered.
  5716.           DB().NumberOne =
  5717.             Length of the returned string (held by DB().TextString).
  5718.  
  5719.  
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.           A - 4
  5726.  
  5727.  
  5728.  
  5729.  
  5730.                                             Appendix A: Dialog Box Elements
  5731.  
  5732.           List Box
  5733.           
  5734.           DB().Code = 3
  5735.             Code for list box.
  5736.           DB().Y = 
  5737.             Y coordinate of upper-left corner.
  5738.           DB().X =
  5739.             X coordinate of upper-left corner.
  5740.           DB().Height =
  5741.             No. items vertically within the list box borders.
  5742.           DB().Wdth =
  5743.             No. items horizontally within the list box borders.
  5744.           DB().WindowColor = 
  5745.             Color of ``empty'' space within list box borders.
  5746.           DB().PrimaryColor =
  5747.             Color of primary list box items.
  5748.           DB().SecondaryColor =
  5749.             Color of secondary list box items.
  5750.           DB().SelectedColor =
  5751.             Color of selected items.
  5752.           DB().StarColor =
  5753.             Color of scroll bars.
  5754.           DB().ItemLength =
  5755.             Length of a single list box item.
  5756.           DB().KeyColor = 
  5757.             Number of spaces between list box columns.
  5758.           DB().BorderType =
  5759.             Scroll bars: 0=none; 1=bottom; 2=side; 3=both.
  5760.           DB().Link =
  5761.             Link code. 0=none; >0=text-box; <0=sentence.
  5762.           DB().TextY =
  5763.             Y coordinate for sentence links.
  5764.           DB().TextX =
  5765.             X coordinate for sentence links.
  5766.           DB().TextColor =
  5767.             Color of sentence links.
  5768.           DB().NumberOne =
  5769.             LB() starting element.
  5770.           DB().NumberTwo =
  5771.             LB() ending element.
  5772.           DB().Default   =
  5773.             The LB() array element number to be selected by default.
  5774.  
  5775.                                                                       A - 5
  5776.  
  5777.  
  5778.  
  5779.  
  5780.           DiaLogic
  5781.  
  5782.           Check Box
  5783.  
  5784.           DB().Code = 4
  5785.             Code for check box.
  5786.           DB().Y =
  5787.             Y coordinate of check box's left bracket.
  5788.           DB().X =
  5789.             X coordinate of check box's left bracket.
  5790.           DB().PrimaryColor =
  5791.             Color when unselected.
  5792.           DB().SelectedColor =
  5793.             Color when selected.
  5794.           DB().TextY =
  5795.             Y coordinate for check box label.
  5796.           DB().TextX =
  5797.             X coordinate for check box label.
  5798.           DB().Text =
  5799.             Check box label.  May contain a tilde for Alt-key
  5800.             function.
  5801.           DB().TextColor =
  5802.             Color of check box label.
  5803.           DB().KeyColor =
  5804.             Color of the alt-key in the check box label.
  5805.           DB().StarColor =
  5806.             Toggle star color.
  5807.           DB().Default = 
  5808.             Default status of check box. 0=off; -1=on.
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.  
  5822.  
  5823.  
  5824.  
  5825.           A - 6
  5826.  
  5827.  
  5828.  
  5829.  
  5830.                                             Appendix A: Dialog Box Elements
  5831.  
  5832.           Option Buttons
  5833.  
  5834.           DB().Code = 5
  5835.             Code for option buttons.
  5836.           DB().NumberOne =
  5837.             Number of option buttons in this cluster.
  5838.           DB().Default =
  5839.             Default option button.
  5840.           DB().TextString =
  5841.             Location  string  holding coordinates  for  each  button in 
  5842.             the cluster.
  5843.           DB().WindowColor =
  5844.             Color of button's parentheses.
  5845.           DB().SelectedColor =
  5846.             Color (of centered dot) when selected.
  5847.           DB().StarColor =
  5848.             Color of toggle star.
  5849.  
  5850.  
  5851.  
  5852.  
  5853.  
  5854.  
  5855.  
  5856.  
  5857.  
  5858.  
  5859.  
  5860.  
  5861.  
  5862.  
  5863.  
  5864.  
  5865.  
  5866.  
  5867.  
  5868.  
  5869.  
  5870.  
  5871.                                                                       A - 7
  5872.  
  5873.  
  5874.  
  5875.  
  5876.           DiaLogic
  5877.  
  5878.           Smart Label
  5879.  
  5880.           DB().Code = 6
  5881.             Code for smart label.
  5882.           DB().Y =
  5883.             Y coordinate of smart label text.
  5884.           DB().X =
  5885.             X coordinate of smart label text.
  5886.           DB().Text =
  5887.             Smart label text.  May contain a tilde for alt-key function.
  5888.           DB().TextColor =
  5889.             Color of smart label.
  5890.           DB().KeyColor =
  5891.             Color of the alt-key in the smart label text.
  5892.           DB().Link =
  5893.             Sequence  of the dialog  box element  which is to  be an
  5894.             Alt-key link to this smart label.
  5895.           DB().NumberOne =
  5896.             Button number for a linked option button cluster.
  5897.  
  5898.  
  5899.  
  5900.  
  5901.  
  5902.  
  5903.  
  5904.  
  5905.  
  5906.  
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.           A - 8
  5920.  
  5921.  
  5922.  
  5923.  
  5924.                                             Appendix A: Dialog Box Elements
  5925.  
  5926.           Command Button
  5927.  
  5928.           DB().Code = 7
  5929.             Code for command button.
  5930.           DB().Y =
  5931.             Y coordinate of upper-left corner.
  5932.           DB().X =
  5933.             X coordinate of upper-left corner.
  5934.           DB().Text =
  5935.             Command button text.  May contain a tilde for Alt-key function.
  5936.           DB().PrimaryColor = 
  5937.             Color of angle brackets when command button is inactive.
  5938.           DB().SecondaryColor =
  5939.            Color of angle brackets when command button is active.
  5940.          DB().WindowColor =
  5941.            Color of text between angle brackets when unselected.
  5942.          DB().SelectedColor =
  5943.            Color of command button when selected.
  5944.          DB().KeyColor =
  5945.            Color of the Alt-key character.
  5946.          DB().Default =
  5947.            Default status: -1=on; 0=off.
  5948.          DB().TextString =
  5949.            Sets Ky$ return value for this command button.  This should be
  5950.            a valid key string, such as CHR$(27) for <Esc>.
  5951.  
  5952.  
  5953.  
  5954.  
  5955.  
  5956.  
  5957.  
  5958.  
  5959.  
  5960.  
  5961.  
  5962.  
  5963.  
  5964.  
  5965.  
  5966.  
  5967.  
  5968.  
  5969.                                                                       A - 9
  5970.  
  5971.  
  5972.  
  5973.  
  5974.           DiaLogic
  5975.  
  5976.           Group Box
  5977.  
  5978.           DB().Code = 8
  5979.             Code for group box.
  5980.           DB().Y =
  5981.             Y coordinate of upper-left corner.
  5982.           DB().X =
  5983.             X coordinate of upper-left corner.
  5984.           DB().Height =
  5985.             Height of box.
  5986.           DB().Wdth =
  5987.             Width of box.
  5988.           DB().BorderType =
  5989.             Border type.
  5990.           DB().SecondaryColor =
  5991.             Color of group box border.
  5992.           DB().Text =
  5993.             Text for the top center of group box.
  5994.           DB().TextColor =
  5995.             Color of the text label.
  5996.  
  5997.  
  5998.  
  5999.  
  6000.  
  6001.  
  6002.  
  6003.  
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.  
  6011.  
  6012.  
  6013.  
  6014.  
  6015.  
  6016.  
  6017.  
  6018.           A - 10
  6019.  
  6020.  
  6021.  
  6022.  
  6023.  
  6024.  
  6025.  
  6026.  
  6027.  
  6028.  
  6029.  
  6030.  
  6031.                                        DiaLogic
  6032.  
  6033.  
  6034.                                       APPENDIX B
  6035.                                 MODIFYING DIALOGIC.BAS
  6036.  
  6037.  
  6038.  
  6039.  
  6040.  
  6041.  
  6042.                                          Appendix B: Modifying DIALOGIC.BAS
  6043.  
  6044.  
  6045.  
  6046.            Note:
  6047.               DIALOGIC.BAS is extremely complex and should you wish to
  6048.               alter it we ask that you preserve an original copy  as a
  6049.               backup.  If  you are trying to  correct what you believe
  6050.               to be a bug, or if you have a suggestion for an improve-
  6051.               ment,  please contact  us.   We will try to quickly
  6052.               correct bugs  and provide  you with a  patch or  update,
  6053.               and we will often incorporate ideas for improvement in
  6054.               a future release.
  6055.  
  6056.  
  6057.           We suggest  two ways  in which DIALOGIC  may be  safely modified.
  6058.           The first concentrates  on reducing the size of  the DIALOGIC.BAS
  6059.           module; the second discusses changing default constants.
  6060.  
  6061.           Reducing the Size
  6062.  
  6063.           The  most desirable reduction will result when the mouse routines
  6064.           are removed.  While you may of course  delete mouse-related code,
  6065.           we suggest using the REM statement.
  6066.  
  6067.           Two  subprograms contain  most of  the  mouse code.   The  first,
  6068.           MouseInput, may  be  fully omitted.    The second  subprogram  is
  6069.           CentralInput,  and  we have  clearly  marked  the  begin and 
  6070.           end portion of the mouse-related code.   To find this easily,    
  6071.           simply search for  a block  of ``MMMMM''  lines.  The  code      
  6072.           between  the first and second block may be completely removed.
  6073.           These omissions  will remove the most  mouse-related instructions
  6074.           and will reduce the size of the DIALOGIC module as a result.
  6075.  
  6076.           An  additional reduction in  size may be achieved  if most of
  6077.           the list-box related code is removed.  Just like the mouse, there
  6078.           are two subprograms which contain the majority of list-box code. 
  6079.           The first is  LBox, and this entire  subprogram may be  REM'd
  6080.           between the  blocks of ``LLLLL'' characters.  A similar operation
  6081.           between ``LLLLL''  blocks  should   be  conducted  in   the      
  6082.           CentralInput subprogram.
  6083.  
  6084.           Changing Default Constants
  6085.  
  6086.  
  6087.  
  6088.           A few  constants are defined at the main module level of         
  6089.           DIALOGIC.BAS.  You may change the value of any of these 
  6090.           constants in accordance with the instructions below:
  6091.  
  6092.           Variable           What it means & how to change it
  6093.  
  6094.           AltKeyClose%        If  -1 then  a dialog box  will close
  6095.                               whenever the input focus is transferred to a
  6096.                               command button using an Alt-key.   If 0 then
  6097.                               a dialog box will not close automatically 
  6098.                               but will wait for <Enter>.  The default is
  6099.                               -1.
  6100.           AutoRepeat!         Holds the auto-repeat  delay when the mouse
  6101.                               is used to scroll text box or  list box
  6102.                               contents.  The default is 0.09 seconds.
  6103.           JustPressedPause!   Holds  the  delay, in  seconds,  before 
  6104.                               auto-repeat is enabled when  a mouse is used. 
  6105.                               The default is 0.3 seconds.
  6106.           MickeyDelay!        Holds the  acceleration delay  when the mouse
  6107.                               is  used  to  scroll  text  box  or  list 
  6108.                               box contents.  The default is 0.01 seconds.
  6109.           ShowAltKey%         If 0 then Alt-keys will not  be revealed
  6110.                               until an <Alt> key is pressed.  If -1,  then
  6111.                               all Alt-keys  will be  shown when  the dialog 
  6112.                               box first opens.  The default is 0.
  6113.           MaxDialog%          Sets the greatest Level  number which
  6114.                               DiaLogic can use.  The  default, 2, means
  6115.                               that  no more than 2 dialog boxes may  be on 
  6116.                               the screen at one  time.    The  value  of 
  6117.                               MaxDialog%  must always   be  equal  to  or 
  6118.                               greater  than the highest Level used by the
  6119.                               calling program.
  6120.           MaxDBE%             Sets  the greatest DBE  number.   The
  6121.                               default, 20,  means that  a single dialog 
  6122.                               box can have no more than 20 dialog box
  6123.                               elements, including the  window.   The value 
  6124.                               of MaxDBE% must  always be  equal to or 
  6125.                               greater than the highest Sequence used by the
  6126.                               calling program.
  6127.  
  6128.  
  6129.  
  6130.  
  6131.                                                                       B - 3
  6132.  
  6133.  
  6134.  
  6135.  
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.  
  6143.  
  6144.                                        DiaLogic
  6145.  
  6146.  
  6147.                                       APPENDIX C
  6148.                                    TROUBLESHOOTING
  6149.  
  6150.  
  6151.  
  6152.  
  6153.  
  6154.  
  6155.                                                 Appendix C: Troubleshooting
  6156.  
  6157.           DiaLogic has been tested  with many dialog  box templates and  we
  6158.           are confident that it can handle most any design.  In general, if
  6159.           there is  a  problem in  the  way that  a particular  dialog  box
  6160.           element, such  as a list  box, is behaving then  we must strongly
  6161.           suggest that you examine its dialog box template.  Often problems
  6162.           arise simply because a  wrong link number  was specified.   Other
  6163.           times a value is out-of-range or used improperly.
  6164.  
  6165.           Nevertheless,  two  brief  sections  are  presented:   Appearance
  6166.           Problems and  Operational Problems.   We  hope some  of our  tips
  6167.           assist you if you encounter difficulty.
  6168.  
  6169.  
  6170.           Appearance Problems
  6171.  
  6172.           Some dialog box elements are off the screen, are not centered, or
  6173.           are missing.
  6174.  
  6175.                Check the template.  Make sure  that the Sequence of the
  6176.                elements in  the DB() array  does not skip or  repeat any
  6177.                numbers.  Check that  the X  and Y  coordinates for  the
  6178.                dialog box elements  are  used  properly.   Remember that
  6179.                these coordinates are  upper-left offsets  from the  dialog
  6180.                box window and not from the screen.  Make  sure  that
  6181.                foreground  colors are  not the  same as background colors. 
  6182.                This will render an item invisible. Make sure  that the
  6183.                screen size is  properly specified in the window definition. 
  6184.                
  6185.           List  box  items  and/or  their  descriptions are  not formatted
  6186.           correctly.
  6187.  
  6188.                Check both the link code used and insure that the strings
  6189.                assigned to the LB() array are properly specified.
  6190.  
  6191.           Out of  memory  occurs  when  the  calling  program  attempts to
  6192.           generate a dialog box.
  6193.  
  6194.                This  will  happen if  the code  segment for  the calling
  6195.                program becomes large  enough that DiaLogic  must use the
  6196.                far heap for its arrays.  This problem is usually solved if
  6197.                all arrays are dynamic and the /AH (huge array) switch is
  6198.                used when compiling  both DIALOGIC.BAS and the modules which
  6199.                make calls to it.
  6200.  
  6201.                                                                       C - 3
  6202.  
  6203.  
  6204.  
  6205.  
  6206.           DiaLogic
  6207.  
  6208.           Functional Problems
  6209.  
  6210.           The mouse does not work yet the mouse is plugged into the
  6211.           computer.
  6212.  
  6213.                Check that the mouse driver is being loaded.  Usually the  
  6214.                driver is specified as  a .COM file in AUTOEXEC.BAT or as
  6215.                a .SYS device driver in CONFIG.SYS.
  6216.  
  6217.                Be sure to use the DiaLogic assembler routines InitMouse,
  6218.                ShowCursor, and  TextCursor.   If TextCursor  is used  be
  6219.                sure that colors are chosen properly.
  6220.  
  6221.           The dialog box is displayed but then ``hangs''.
  6222.  
  6223.                Insure that the last  template assignment sets  DB().Code
  6224.                to 0.  Make  sure  that the  DB() and  LB() arrays  are
  6225.                properly dimensioned.  
  6226.  
  6227.                Check your include  file for the presence  of the 
  6228.                right-arrow symbol.   This symbol is the same as the DOS
  6229.                end-of-file character (ASCII 26), and cannot be used as a
  6230.                literal in an include file.  Use CHR$(26) instead.
  6231.  
  6232.           Ky$  returns  wrong information  about  which command  button was
  6233.           pushed.
  6234.  
  6235.               This  problem  occurs   when  DB().TextString  is  either
  6236.               assigned incorrectly for  a command  buttons or  when two
  6237.               command buttons have the same DB().TextString defined.
  6238.  
  6239.  
  6240.  
  6241.  
  6242.  
  6243.  
  6244.  
  6245.  
  6246.  
  6247.  
  6248.  
  6249.  
  6250.  
  6251.           C - 4
  6252.  
  6253.  
  6254.  
  6255.  
  6256.  
  6257.  
  6258.  
  6259.  
  6260.  
  6261.  
  6262.  
  6263.  
  6264.                                        DiaLogic
  6265.  
  6266.  
  6267.                                       APPENDIX D
  6268.                                      COLOR CHART
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.                                   Appendix D: Color Chart
  6276.  
  6277.  
  6278.                                     Color Chart
  6279.  
  6280.                                     BACKGROUND
  6281.  
  6282.                Black   Blue  Green   Cyan  Red  Magenta Brown  White
  6283.      Black        0     16      32    48    64     80     96    112
  6284.      Blue         1     17      33    49    65     81     97    113
  6285.      Green        2     18      34    50    66     82     98    114
  6286. F    Cyan         3     19      35    51    67     83     99    115
  6287. O    Red          4     20      36    52    68     84    100    116
  6288. R    Magenta      5     21      37    53    69     85    101    117
  6289. E    Brown        6     22      38    54    70     86    102    118
  6290. G    White        7     23      39    55    71     87    103    119
  6291. R    Br Black     8     24      40    56    72     88    104    120
  6292. O    Br Blue      9     25      41    57    73     89    105    121
  6293. U    Br Green    10     26      42    58    74     90    106    122
  6294. N    Br Cyan     11     27      43    59    75     91    107    123
  6295. D    Br Red      12     28      44    60    76     92    108    124
  6296.      Br Magenta  13     29      45    61    77     93    109    125
  6297.      Br Brown    14     30      46    62    78     94    110    126
  6298.      Br White    15     31      47    63    79     95    111    127
  6299.  
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.                                                                       D - 3
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.     
  6332.  
  6333.  
  6334.  
  6335.  
  6336.                                        DiaLogic
  6337.  
  6338.  
  6339.                                       APPENDIX E
  6340.                                 ASCII CHARACTER CHARTS
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.  
  6347.                                                    Appendix E: ASCII
  6348. Character Charts
  6349.  
  6350.                  Conventional ASCII Character Codes
  6351.  
  6352. 000    (nul) 016 ^P (dle) 032 sp 048 0  064 @  080 P  096 `  112 p
  6353. 001 ^A (soh) 017 ^Q (dc1) 033 !  049 1  065 A  081 Q  097 a  113 q
  6354. 002 ^B (stx) 018 ^R (dc2) 034 "  050 2  066 B  082 R  098 b  114 r
  6355. 003 ^C (etx) 019 ^S (dc3) 035 #  051 3  067 C  083 S  099 c  115 s
  6356. 004 ^D (eot) 020 ^T (dc4) 036 $  052 4  068 D  084 T  100 d  116 t
  6357. 005 ^E (enq) 021 ^U (nak) 037 %  053 5  069 E  085 U  101 e  117 u
  6358. 006 ^F (ack) 022 ^V (syn) 038 &  054 6  070 F  086 V  102 f  118 v
  6359. 007 ^G (bel) 023 ^W (etb) 039 '  055 7  071 G  087 W  103 g  119 w
  6360. 008 ^H (bs)  024 ^X (can) 040 (  056 8  072 H  088 X  104 h  120 x
  6361. 009    (tab) 025 ^Y (em)  041 )  057 9  073 I  089 Y  105 i  121 y
  6362. 010    (lf)  026 ^Z (eof) 042 *  058 :  074 J  090 Z  106 j  122 z
  6363. 011    (vt)  027 ^[ (esc) 043 +  059 ;  075 K  091 [  107 k  123 {
  6364. 012    (np)  028 ^\ (fs)  044 ,  060 <  076 L  092 \  108 l  124 |
  6365. 013    (cr)  029 ^] (gs)  045 -  061 =  077 M  093 ]  109 m  125 }
  6366. 014 ^N (so)  030 ^^ (rs)  046 .  062 >  078 N  094 ^  110 n  126 ~
  6367. 015 ^O (si)  031 ^_ (us)  047 /  063 ?  079 O  095 _  111 o  127  
  6368.  
  6369.          Extended ASCII Chart (character codes 128 - 255)
  6370. 128     144      160      176      192      208      224     240  
  6371. 129     145      161      177      193      209      225     241  
  6372. 130     146      162      178      194      210      226     242
  6373. 131     147      163      179      195      211      227     243  
  6374. 132     148      164      180      196      212      228     244  
  6375. 133     149      165      181      197      213      229     245  
  6376. 134     150      166      182      198      214      230     246  
  6377. 135     151      167      183      199      215      231     247  
  6378. 136     152      168      184      200      216      232     248  
  6379. 137     153      169      185      201      217      233     249  
  6380. 138     154      170      186      202      218      234     250  
  6381. 139     155      171      187      203      219      235     251  
  6382. 140     156      172      188      204      220      236     252  
  6383. 141     157      173      189      205      221      237     253  
  6384. 142     158      174      190      206      222      238     254  
  6385. 143     159      175      191      207      223      239     255 
  6386.  
  6387. Notes:
  6388.  
  6389.      127   triangular symbol
  6390.      152   "y" with umlaut
  6391.      231   upsilon
  6392.      251   check mark
  6393.  
  6394.                                                                           
  6395.     E - 3
  6396.  
  6397.  
  6398.  
  6399.  
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.  
  6407.  
  6408.                                        DiaLogic
  6409.  
  6410.  
  6411.                                        GLOSSARY
  6412.  
  6413.  
  6414.  
  6415.  
  6416.                                                                    Glossary
  6417.  
  6418.           alt-key:  
  6419.                A character from 0 to 9 or from ``A'' to  ``Z'' which is
  6420.                pressed while  the <Alt>  key is held  down.   Alt-keys
  6421.                typically transfer the  input focus and  provide direct
  6422.                access  to a dialog box element without having to use the
  6423.                mouse.
  6424.           active command button:
  6425.                The  command button which has its angle brackets
  6426.                highlighted.  
  6427.           check box:
  6428.                The  dialog box element which  allows an option  to be
  6429.                toggled on or off.
  6430.           click:
  6431.                 A  mouse  operation  where  the  mouse  cursor  is  placed
  6432.                ``over'' a portion  of the screen and  a mouse button is
  6433.                quickly pressed and released.  
  6434.           command button:
  6435.                The  dialog box element which returns  control to the
  6436.                calling program  when selected.  Typical command buttons are
  6437.                <OK> and <Cancel>.  
  6438.           directional  keys:
  6439.                Usually considered  to be any  key which moves the cursor.  
  6440.                These keys  include the right,  left, up, and down arrows;  
  6441.                <PgUp>,   <PgDn>;  and   <Home>   and  <End>   in  some
  6442.                circumstances.
  6443.           DBE: 
  6444.                See dialog box element.
  6445.           dialog  box:
  6446.                An  aesthetic data-entry  screen  which, as  a popup window,
  6447.                can appear  and disappear  without disturbing the screen
  6448.                contents.   Dialog  boxes provide  a  standard interface 
  6449.                and are fully compatible with a mouse.
  6450.           dialog box element:
  6451.                Any  of the eight building blocks of a dialog box:  the
  6452.                window, text box, list  box, check box, option buttons,
  6453.                smart label, command button, and group box.
  6454.           double-click:
  6455.                A mouse operation where the mouse cursor is placed``over'' a 
  6456.                portion of the  screen and a mouse  button is pressed and
  6457.                released two times in rapid succession.  
  6458.           drag:
  6459.                A mouse  operation which  describes  holding down  a mouse
  6460.                button while moving the mouse cursor.  
  6461.           group box:
  6462.                The dialog  box element which  frames regions  of the dialog
  6463.                box. 
  6464.  
  6465. Glossary - 3
  6466.  
  6467.           DiaLogic
  6468.  
  6469.  
  6470.           input focus:
  6471.                The  current position  of the cursor  on the  dialog box. 
  6472.                The input focus rests on the dialog box element which is
  6473.                prepared to accept input.
  6474.           level:
  6475.                Refers to  a dialog box template  in the DB() array.   The
  6476.                Level is the first subscript of this array.
  6477.           link:
  6478.                For list boxes:  provides a way  to place a  list box item
  6479.                somewhere else on the dialog box.   For smart labels:
  6480.                provides a way to associate an Alt-key with a dialog box
  6481.                element.
  6482.           list box:
  6483.                The dialog box element which presents a scrollable list     
  6484.                of items. 
  6485.           option  buttons: 
  6486.                The dialog  box element which  allows one option from a
  6487.                group to be selected.            
  6488.           polling:
  6489.                A method of calling a program (a function or subroutine)
  6490.                repeatedly in a  loop.  Polling can simulate  multi-tasking
  6491.                since more than one process may be executed in turn while in
  6492.                the loop.
  6493.           primary dialog  box:
  6494.                The  dialog box which  first appears  on the screen.
  6495.           scroll:
  6496.                An operation, usually mediated by the directional keys on
  6497.                the keyboard or by dragging the mouse, which shifts text in
  6498.                a text box or list box.
  6499.           scroll bar: 
  6500.                An  optional list box component which contains a moving 
  6501.                pointer indicating  the  relative  amount of  information   
  6502.                remaining on either side of the  cursor.  Scroll bars have 
  6503.                arrow symbols which may be clicked on with the mouse to move
  6504.                the cursor one line at  a time within the  list box.  The 
  6505.                space between the scroll bar  pointer and the  arrow symbols 
  6506.                may be clicked  on in  order  to  scroll several  lines at 
  6507.                one time.   Scroll bars may appear on the right or bottom
  6508.                border of a list box.
  6509.           scroll bar  pointer:
  6510.                A  dark block which appears on an optional scroll bar once a
  6511.                list box is accessed.  The pointer moves along the scroll
  6512.                bar as list  box contents are  scrolled.  The pointer may be
  6513.                repositioned by dragging it with the mouse.
  6514.  
  6515.  
  6516. Glossary - 4 
  6517.  
  6518.                                                                    Glossary
  6519.  
  6520.           secondary  dialog  box:
  6521.                A  dialog  box  which  is stacked  on  an existing primary
  6522.                dialog box.
  6523.           select:
  6524.                Usually  refers   to  text   which  is  highlighted   in
  6525.                preparation for a delete or copy operation but also refers
  6526.                to thechoice of a particular option.
  6527.           Sequence:
  6528.                The  order in which the  dialog box elements  appear in the
  6529.                DB() array.  The Sequence is the second subscript in the
  6530.                DB() array.
  6531.           smart label:
  6532.                The dialog box element which places text anywhere on the
  6533.                dialog box and may also form Alt-key links to other dialog
  6534.                box elements.
  6535.           stacked  dialog  boxes:
  6536.                Two or more dialog boxes which are displayed on the screen
  6537.                simultaneously and appear to be on top of one another. 
  6538.           text box:
  6539.                The dialog box element which accepts text.           
  6540.           
  6541.           
  6542.           
  6543.           
  6544.           
  6545.           
  6546.           
  6547.           
  6548.           
  6549.           
  6550.           
  6551.           
  6552.           
  6553.           
  6554.           
  6555.           
  6556.           
  6557.           
  6558.           
  6559.           
  6560.           
  6561.           
  6562.           
  6563.           
  6564.           
  6565.           
  6566.           
  6567.           
  6568.           
  6569.           
  6570.           
  6571.           
  6572.           
  6573.           
  6574.           
  6575.           
  6576.           
  6577.           
  6578.           
  6579.           
  6580.           
  6581.           
  6582.           
  6583.           
  6584.           
  6585.           
  6586.           
  6587.           
  6588.